From 0e8fd3398771da2f016d72830179507f3edda51b Mon Sep 17 00:00:00 2001 From: Samba Release Account Date: Sat, 4 May 1996 07:50:46 +0000 Subject: Initial version imported to CVS (This used to be commit 291551d80711daab7b7581720bcd9a08d6096517) --- docs/THANKS | 119 ++ docs/announce | 129 ++ docs/history | 165 +++ docs/htmldocs/wfw_slip.htm | 175 +++ docs/manpages/nmbd.8 | 491 ++++++++ docs/manpages/samba.7 | 190 +++ docs/manpages/smb.conf.5 | 2719 ++++++++++++++++++++++++++++++++++++++++ docs/manpages/smbclient.1 | 1133 +++++++++++++++++ docs/manpages/smbd.8 | 407 ++++++ docs/manpages/smbrun.1 | 70 ++ docs/manpages/smbstatus.1 | 52 + docs/manpages/smbtar.1 | 167 +++ docs/manpages/testparm.1 | 104 ++ docs/manpages/testprns.1 | 107 ++ docs/samba.lsm | 26 + docs/textdocs/BROWSING.txt | 145 +++ docs/textdocs/BUGS.txt | 123 ++ docs/textdocs/DIAGNOSIS.txt | 237 ++++ docs/textdocs/DNIX.txt | 69 + docs/textdocs/DOMAIN.txt | 68 + docs/textdocs/ENCRYPTION.txt | 333 +++++ docs/textdocs/HINTS.txt | 202 +++ docs/textdocs/INSTALL.sambatar | 27 + docs/textdocs/PROJECTS | 96 ++ docs/textdocs/Passwords.txt | 42 + docs/textdocs/README.DCEDFS | 79 ++ docs/textdocs/README.jis | 124 ++ docs/textdocs/README.sambatar | 15 + docs/textdocs/SCO.txt | 12 + docs/textdocs/SMBTAR.notes | 40 + docs/textdocs/Speed.txt | 272 ++++ docs/textdocs/Support.txt | 376 ++++++ docs/textdocs/UNIX-SMB.txt | 220 ++++ docs/textdocs/WinNT.txt | 56 + 34 files changed, 8590 insertions(+) create mode 100644 docs/THANKS create mode 100644 docs/announce create mode 100644 docs/history create mode 100644 docs/htmldocs/wfw_slip.htm create mode 100644 docs/manpages/nmbd.8 create mode 100644 docs/manpages/samba.7 create mode 100644 docs/manpages/smb.conf.5 create mode 100644 docs/manpages/smbclient.1 create mode 100644 docs/manpages/smbd.8 create mode 100644 docs/manpages/smbrun.1 create mode 100644 docs/manpages/smbstatus.1 create mode 100644 docs/manpages/smbtar.1 create mode 100644 docs/manpages/testparm.1 create mode 100644 docs/manpages/testprns.1 create mode 100644 docs/samba.lsm create mode 100644 docs/textdocs/BROWSING.txt create mode 100644 docs/textdocs/BUGS.txt create mode 100644 docs/textdocs/DIAGNOSIS.txt create mode 100644 docs/textdocs/DNIX.txt create mode 100644 docs/textdocs/DOMAIN.txt create mode 100644 docs/textdocs/ENCRYPTION.txt create mode 100644 docs/textdocs/HINTS.txt create mode 100644 docs/textdocs/INSTALL.sambatar create mode 100644 docs/textdocs/PROJECTS create mode 100644 docs/textdocs/Passwords.txt create mode 100644 docs/textdocs/README.DCEDFS create mode 100644 docs/textdocs/README.jis create mode 100644 docs/textdocs/README.sambatar create mode 100644 docs/textdocs/SCO.txt create mode 100644 docs/textdocs/SMBTAR.notes create mode 100644 docs/textdocs/Speed.txt create mode 100644 docs/textdocs/Support.txt create mode 100644 docs/textdocs/UNIX-SMB.txt create mode 100644 docs/textdocs/WinNT.txt (limited to 'docs') diff --git a/docs/THANKS b/docs/THANKS new file mode 100644 index 0000000000..6405da3f9f --- /dev/null +++ b/docs/THANKS @@ -0,0 +1,119 @@ +===================================================================== +This file is for thanks to individuals or organisations who have +helped with the development of Samba, other than by coding or bug +reports. Their contributions are gratefully acknowledged. + +Please refer to the manual pages and change-log for a list of those +who have contributed in the form of patches, bug fixes or other +direct changes to the package. + +Contributions of any kind are welcomed. If you want to help then +please contact Andrew.Tridgell@anu.edu.au, or via normal mail at + + Andrew Tridgell + 3 Ballow Crescent + Macgregor, A.C.T + 2615 Australia +===================================================================== + + +Lee Fisher (leefi@microsoft.com) +Charles Fox (cfox@microsoft.com) +Dan Perry (danp@exchnge.microsoft.com) + + These Microsoft people have been very helpful and supportive of + the development of Samba. + + Lee very kindly supplied me with a copy of the X/Open SMB + specs. These have been invaluable in getting the details of the + implementation right. They will become even more important as we move + towards a Lanman 2.1 compliant server. Lee has provided very + useful advice on several aspects of the server. + Lee has also provided me with copies of Windows NTAS 3.1, Visual C + and a developers CD-ROM. Being able to run NT at home is a + great help. + + Charles has helped out in numerous ways with the provision of SMB + specifications and helpful advice. He has been following the + discussion of Samba on the mailing list and has stepped in + regularly to clarify points and to offer help. + + Dan has put me in touch with NT developers to help sort out bugs and + compatability issues. He has also supplied me with a copy of the + NT browsing spec, which will help a lot in the development of the + Samba browser code. + + +Bruce Perens (bruce@pixar.com) + + In appreciation of his effort on Samba we have sent Andrew copies of + various Pixar computer-graphics software products. Pixar is best known + for its "Renderman" product, the 3-D renderer used by ILM to make special + effects for "Terminator II" and "Jurassic Park". We won the first Oscar + given to a computer graphic animated feature for our short film "Tin Toy". + Our retail products "Typestry" and "Showplace", incorporate the same + renderer used on the films, and are available on Windows and the + Macintosh. + + + +Henry Lee (hyl@microplex.co) + + Henry sent me a M202 ethernet print server, making my little lan + one of the few home networks to have it's own print server! + + ``Microplex Systems Ltd. is a manufacturer of local and wide area + network communications equipment based in beautiful Vancouver, British + Columbia, Canada. Microplex's first products were synchronous wide + area network devices used in the mainframe communication networks. In + August 1991 Microplex introduced its first LAN product, the M200 print + server, the first high performance print server under US$1,000.'' + + +Tom Haapanen (tomh@metrics.com) + + Tom sent me two 16 bit SMC ethernet cards to replace my ancient 8 + bit ones. The performance is much better! + + Software Metrics Inc. is a small custom software development and + consulting firm located in Waterloo, Ontario, Canada. We work + with a variety of environments (such as Windows, Windows NT and + Unix), tools and application areas, and can provide assistance for + development work ranging from a few days to to multiple man-year + projects. You can find more information at http://www.metrics.com/. + + +Steve Kennedy (steve@gbnet.net) + + Steve sent me 16Mb of ram so that I could install/test + NT3.5. I previous had only 8Mb ram in my test machine, which + wasn't enough to install a properly functioning copy of + NTAS. Being able to directly test NT3.5 allowed me to solve + several long standing NT<->Samba problems. Thanks Steve! + +John Terpstra (jht@aquasoft.com.au) + + Aquasoft are a speciaist consulting company whose Samba using + customers span the world. + + Aquasoft have been avid supporters of the Samba project. As a + token of appreciation Aquasoft have donated a 486DX2/66 PC with + a 540MB EIDE drive and 20MB RAM. + + John has helped to isolate quite a few little glitches over time + and has managed to implement some very interesting installations + of Samba. + + The donation of the new PC will make it possible to more fully + diagnose and observe the behaviour of Samba in conjuction with + other SMB protocol utilising systems. + + +Timothy F. Sipples (tsipple@vnet.IBM.COM) +Steve Withers (swithers@vnet.IBM.COM) + + Tim and Steve from IBM organised a copy of the OS/2 developers + connection CD set for me, and gave lots of help in getting + OS/2 Warp installed. I hope this will allow me to finally fix + up those annoying OS/2 related Samba bugs that I have been + receiving reports of. diff --git a/docs/announce b/docs/announce new file mode 100644 index 0000000000..f761320f43 --- /dev/null +++ b/docs/announce @@ -0,0 +1,129 @@ + Announcing Samba version 1.9 + ============================ + +What is Samba? +-------------- + +Samba is a Unix based SMB file server. This allows a Unix host to +act as a file and print server for SMB clients. This includes +Lan-Manager compatible clients such as LanManager for DOS, Windows for +Workgroups, Windows NT, Windows 95, OS/2, Pathworks and many more. + +The package also includes a Unix SMB client and a netbios nameserver. + +What can it do for me? +---------------------- + +If you have any PCs running SMB clients, such as a PC running Windows +for Workgroups, then you can mount file space or printers from a unix +host, so that directories, files and printers on the unix host are +available on the PC. + +The client part of the package will also allow you to attach to other +SMB-based servers (such as windows NT and windows for workgroups) so +that you can copy files to and from your unix host. The client also +allows you to access a SMB printer (such as one attached to an OS/2 or +WfWg server) from Unix, using an entry in /etc/printcap, or by +explicitly specifying the command used to print files. + +What are it's features? +------------------------ + +Samba supports many features that are not supported in other SMB +implementations (all of which are commercial). Some of it's features +include host as well as username/password security, a unix client, +automatic home directory exporting, automatic printer exporting, dead +connection timeouts, umask support, guest connections, name mangling +and hidden and system attribute mapping. Look at the man pages +included with the package for a full list of features. + +What's new since 1.8? +--------------------- + +Lots of stuff. See the change log and man pages for details. + +Where can I get a client for my PC? +----------------------------------- + +There is a free client for MS-DOS based PCs available from +ftp.microsoft.com in the directory bussys/Clients/MSCLIENT/. Please +read the licencing information before downloading. The built in +Windows for Workgroups client is also very good. + +What network protocols are supported? +------------------------------------- + +Currently only TCP/IP is supported. There has been some discussion +about ports to other protocols but nothing is yet available. + +There is a free TCP/IP implementation for Windows for Workgroups +available from ftp.microsoft.com (it's small, fast and quite reliable). + +How much does it cost? +---------------------- + +Samba software is free software. It is available under the +GNU Public licence in source code form at no cost. Please read the +file COPYING that comes with the package for more information. + +What flavours of unix does it support? +--------------------------------------- + +The code has been written to be as portable as possible. It has been +"ported" to many unixes, which mostly required changing only a few +lines of code. It has been run (to my knowledge) on at least these +unixes: + +Linux, SunOS, Solaris, SVR4, Ultrix, OSF1, AIX, BSDI, NetBSD, +Sequent, HP-UX, SGI, FreeBSD, NeXT, ISC, A/UX, SCO, Intergraph, +Domain/OS and DGUX. + +Some of these have received more testing than others. If it doesn't +work with your unix then it should be easy to fix. + +Who wrote it? +------------- + +Many people on the internet have contributed to the development of +Samba. The maintainer and original author is Andrew Tridgell, but +large parts of the package were contributed by several people from all +over the world. Please look at the file `change-log' for information +on who did what bits. + +Where can I get it? +------------------- + +The package is available via anonymous ftp from nimbus.anu.edu.au in +the directory pub/tridge/samba/. + +What about SMBServer? +--------------------- + +Samba used to be known as SMBServer, until it was pointed out that +Syntax, who make a commercial Unix SMB based server, have trademarked +that name. The name was then changed to Samba. Also, in 1992 a very +early incarnation of Samba was distributed as nbserver. + +If you see any copies of nbserver or smbserver on ftp sites please let +me or the ftp archive maintainer know, as I want to get them deleted. + +Where can I get more info? +--------------------------- + +Please join the mailing list if you want to discuss the development or +use of Samba. To join the mailing list send mail to +listproc@listproc.anu.edu.au with a body of "subscribe samba Your +Name". + +There is also an announcement mailing list for new version +announcements. Subscribe as above but with "subscribe samba-announce +Your Name". + +There is also often quite a bit of discussion about Samba on the +newsgroup comp.protocols.smb. + +A WWW site with lots of Samba info can be found at +http://lake.canberra.edu.au/pub/samba/ + +Andrew Tridgell (Contact: samba-bugs@anu.edu.au) +January 1995 diff --git a/docs/history b/docs/history new file mode 100644 index 0000000000..83761e23b8 --- /dev/null +++ b/docs/history @@ -0,0 +1,165 @@ +Note: This file is now quite out of date - but perhaps that's +appropriate? + + +========= + +This is a short history of this project. It's not supposed to be +comprehensive, just enough so that new users can get a feel for where +this project has come from and maybe where it's going to. + +The whole thing really started in December 1991. I was (and still am) +a PhD student in the Computer Sciences Laboratory at the Australian +Netional University, in Canberra, Australia. We had just got a +beta copy of eXcursion from Digital, and I was testing it on my PC. At +this stage I was a MS-DOS user, dabbling in windows. + +eXcursion ran (at the time) only with Dec's `Pathworks' network for +DOS. I had up till then been using PC-NFS to connect to our local sun +workstations, and was reasonably happy with it. In order to run +pathworks I had to stop using PC-NFS and try using pathworks to mount +disk space. Unfortunately pathworks was only available for digital +workstations running VMS or Ultrix so I couldn't mount from the suns +anymore. + +I had access to a a decstation 3100 running Ultrix that I used to +administer, and I got the crazy notion that the protocol that +pathworks used to talk to ultrix couldn't be that hard, and maybe I +could work it out. I had never written a network program before, and +certainly didn't know what a socket was. + +In a few days, after looking at some example code for sockets, I +discovered it was pretty easy to write a program to "spy" on the file +sharing protocol. I wrote and installed this program (the sockspy.c +program supplied with this package) and captured everything that the +pathworks client said to the pathworks server. + +I then tried writing short C programs (using Turbo C under DOS) to do +simple file operations on the network drive (open, read, cd etc) and +looked at the packets that the server and client exchanged. From this +I worked out what some of the bytes in the packets meant, and started +to write my own program to do the same thing on a sun. + +After a day or so more I had my first successes and actually managed +to get a connection and to read a file. From there it was all +downhill, and a week later I was happily (if a little unreliably) +mounting disk space from a sun to my PC running pathworks. The server +code had a lot of `magic' values in it, which seemed to be always +present with the ultrix server. It was not till 2 years later that I +found out what all these values meant. + +Anyway, I thought other people might be interested in what I had done, +so I asked a few people at uni, and noone seemed much interested. I +also spoke to a person at Digital in Canberra (the person who had +organised a beta test of eXcursion) and asked if I could distribute +what I'd done, or was it illegal. It was then that I first heard the +word "netbios" when he told me that he thought it was all covered by a +spec of some sort (the netbios spec) and thus what I'd done was not +only legal, but silly. + +I found the netbios spec after asking around a bit (the RFC1001 and +RFC1002 specs) and found they looked nothing like what I'd written, so +I thought maybe the Digital person was mistaken. I didn't realise RFCs +referred to the name negotiation and packet encapsulation over TCP/IP, +and what I'd written was really a SMB implementation. + +Anyway, he encouraged me to release it so I put out "Server 0.1" in +January 1992. I got quite a good response from people wanting to use +pathworks with non-digital unix workstations, and I soon fixed a few +bugs, and released "Server 0.5" closely followed by "Server 1.0". All +three releases came out within about a month of each other. + +At this point I got an X Terminal on my desk, and I no longer needed eXcursion +and I prompty forgot about the whole project, apart from a few people +who e-mailed me occasionally about it. + +Nearly two years then passed with just occasional e-mails asking about +new versions and bugs. I even added a note to the ftp site asking for +a volunteer to take over the code as I no longer used it. No one +volunteered. + +During this time I did hear from a couple of people who said it should +be possible to use my code with Lanmanager, but I never got any +definite confirmation. + +One e-mail I got about the code did, however, make an impression. It +was from Dan Shearer at the university of South Australia, and he said +this: + + + I heard a hint about a free Pathworks server for Unix in the + Net channel of the Linux list. After quite a bit of chasing + (and lots of interested followups from other Linux people) I + got hold of a release news article from you, posted in Jan 92, + from someone in the UK. + + Can you tell me what the latest status is? I think you might + suddenly find a whole lot of interested hackers in the Linux + world at least, which is a place where things tend to happen + fast (and even some reliable code gets written, BION!) + +I asked him what Linux was, and he told me it was a free Unix for PCs. +This was in November 1992 and a few months later I was a Linux +convert! I still didn't need a pathworks server though, so I didn't do +the port, but I think Dan did. + +At about this time I got an e-mail from Digital, from a person working +on the Alpha software distribution. He asked if I would mind if they +included my server with the "contributed" cd-rom. This was a bit of a +shock to me as I never expected Dec to ask me if they could use my +code! I wrote back saying it was OK, but never heard from him again. I +don't know if it went on the cd-rom. + +Anyway, the next big event was in December 1993, when Dan again sent +me an e-mail saying my server had "raised it's ugly head" on +comp.protocols.tcpip.ibmpc. I had a quick look on the group, and was +surprised to see that there were people interested in this thing. + +At this time a person from our computer center offered me a couple of +cheap ethernet cards (3c505s for $15 each) and coincidentially someone +announced on one of the Linux channels that he had written a 3c505 +driver for Linux. I bought the cards, hacked the driver a little and +setup a home network between my wifes PC and my Linux box. I then +needed some way to connect the two, and I didn't own PC-NFS at home, +so I thought maybe my server could be useful. On the newsgroup among +the discussions of my server someone had mentioned that there was a +free client that might work with my server that Microsoft had put up +for ftp. I downloaded it and found to my surprise that it worked first +time with my `pathworks' server! + +Well, I then did a bit of hacking, asked around a bit and found (I +think from Dan) that the spec I needed was for the "SMB" protocol, and +that it was available via ftp. I grabbed it and started removing all +those ugly constants from the code, now that all was explained. + +On December 1st 1993 I announced the start of the "Netbios for Unix" +project, seeding the mailing list with all the people who had e-mailed +me over the years asking about the server. + +About 35 versions (and two months) later I wrote a short history of +the project, which you have just read. There are now over a hundred +people on the mailing list, and lots of people report that they use +the code and like it. In a few days I will be announcing the release +of version 1.6 to some of the more popular (and relevant) newsgroups. + + +Andrew Tridgell +6th February 1994 + +--------------------- + +It is now May 1995 and there are about 1400 people on the mailing +list. I got downloads from the main Samba ftp site from around 5000 +unique hosts in a two month period. There are several mirror +sites as well. The current version number is 1.9.13. + +--------------------- + + +--------------------- +It's now March 1996 and version 1.9.16alpha1 has just been +released. There have been lots of changes recently with master browser +support and the ability to do domain logons etc. Samba has also been +ported to OS/2, the amiga and NetWare. There are now 3000 people on +the samba mailing list. +--------------------- diff --git a/docs/htmldocs/wfw_slip.htm b/docs/htmldocs/wfw_slip.htm new file mode 100644 index 0000000000..5b4a0a5e53 --- /dev/null +++ b/docs/htmldocs/wfw_slip.htm @@ -0,0 +1,175 @@ + + +Peter Karrer Announces SLIP for WFW + + +

Winserve

+
+

Peter Karrer Announces SLIP for WFW

+[NEW 03-22-95) +
+Hello, +

+I've discovered a way to run WfW's TCP/IP-32 over a SLIP packet driver. This +allows WfW users to do Windows networking over dialup lines just like it is +possible with NT and the Windows 95 beta! +

+For instance, you can mount Microsoft's FTP server as a network drive in File +Manager or connect to an MS Mail post office over the Internet. Of course, +the usual Internet stuff works as well. Another interesting site is +WINSERVE.001; check out www.winserve.com. +

+This method should work with any class 1 (Ethernet II) packet driver. However, +I'm not in a position to try anything else than SLIPPER/CSLIPPER. +
+

Files you need:

+WFWT32.EXE: ftp://ftp.microsoft.com/bussys/msclient/wfw/wfwt32.exe +

+ Microsoft's free TCP/IP for WfW. It's a self-extracting archive which + should be executed in an empty directory. +

+SLIPPER.EXE: ftp://biocserver.bioc.cwru.edu/pub/dos/slipper/slippr15.zip +

+ Peter Tattam's SLIP packet driver. CSLIPPER.EXE is a variant which supports + VJ header compression. +

+PDETHER.EXE: ftp://sjf-lwp.idz.sjf.novell.com/odi/pdether/pde105.zip +

+ Don Provan's ODI-over-Packet Driver shim. This *must* be version 1.05 (or + above). +

+LSL.COM: +

+ Novell's LAN Support Layer. If you're an owner of Windows 3.10, you'll + have it on one of your install disks. Use "expand a:lsl.co_ lsl.com" to + expand it. Microsoft has stopped bundling LSL.COM with WfW 3.11, though. + The newest version of LSL.COM can be downloaded as part of + ftp://ftp.novell.com/pub/netware/nwos/dosclnt12/vlms/vlmup2.exe. + However, it's not clear if this one may be legally used outside Netware + environments. +

+NET.CFG: +

+ A configuration file for LSL and PDETHER. It should contain the following + text: +

+

+Link Support
+        Buffers 8 1600
+Link Driver PDETHER
+        Int 60
+        Frame Ethernet_II
+        Protocol IP   800  Ethernet_II
+        Protocol ARP  806  Ethernet_II
+        Protocol RARP 8035 Ethernet_II
+
+

+DISCOMX.COM: +

+ A little hack of mine to disable the COM port used by the SLIP packet driver. + Usage is e.g. "discomx 2" to disable COM2. This should be run before + starting WfW, otherwise you'll get "device conflict" messages. Here it is: +

+begin 644 discomx.com
+F,=N)V8H.@`"P(+^!`/.N3XH="=MT!DN`XP/1XS')!R:)CP`$S2``
+`
+end
+
+ (Save this text to disk as filename, then run "uudecode filename". + uudecode can be found, for instance, at + ftp://ftp.switch.ch/mirror/simtel/msdos/starter/uudecode.com ) +

+LMHOSTS: +

+ An optional file which should be stored in your Windows subdirectory. It is + used to map NetBIOS computer names to IP addresses. Example: +

+

+198.105.232.1   ftp             #PRE  # ftp.microsoft.com
+204.118.34.11   winserve.001    #PRE  # Winserve
+
+
+

How to install it:

+

+

+
+

How it works:

+

+Microsoft's TCP/IP-32 requires an NDIS3 interface. NDIS is Microsoft's way +to interface with a network. +

+WfW also contains an NDIS3-over-ODI "shim", whose real mode component is +ODIHLP.EXE. ODI is Novell's way to interface with a network. +

+SLIPPER is a Packet Driver (PD) for use over serial lines. PDs are everybody +else's way to interface with a network. SLIPPER's "ether" option makes it +look like an Ethernet PD to applications using it. +

+A "shim" is a program which simulates a network application programming +interface on top of another. +

+There is no NDIS SLIP driver which would work with WfW. +

+There is no NDIS-over-PD shim. +

+However, there's an ODI-over-PD shim (PDETHER) and an NDIS-over-ODI shim +(ODIHLP etc.) +

+OK, so let's do NDIS-over-ODI-over-PD! +

+This should have worked all the time; however, a non-feature in PDETHER +versions < 1.05 has prevented the method from functioning until now. +

+Questions, suggestions etc. please to +

+

+Peter Karrer		pkarrer@ife.ee.ethz.ch
+
+ + + diff --git a/docs/manpages/nmbd.8 b/docs/manpages/nmbd.8 new file mode 100644 index 0000000000..e42f194cde --- /dev/null +++ b/docs/manpages/nmbd.8 @@ -0,0 +1,491 @@ +.TH NMBD 8 17/1/1995 nmbd nmbd +.SH NAME +nmbd \- provide netbios nameserver support to clients +.SH SYNOPSIS +.B nmbd +[ +.B -B +.I broadcast address +] [ +.B -I +.I IP address +] [ +.B -D +] [ +.B -C comment string +] [ +.B -G +.I group name +] [ +.B -H +.I netbios hosts file +] [ +.B -N +.I netmask +] [ +.B -d +.I debuglevel +] [ +.B -l +.I log basename +] [ +.B -n +.I netbios name +] [ +.B -p +.I port number +] [ +.B -s +.I config file name +] + +.SH DESCRIPTION +This program is part of the Samba suite. + +.B nmbd +is a server that understands and can reply to netbios +name service requests, like those produced by LanManager +clients. It also controls browsing. + +LanManager clients, when they start up, may wish to locate a LanManager server. +That is, they wish to know what IP number a specified host is using. + +This program simply listens for such requests, and if its own name is specified +it will respond with the IP number of the host it is running on. "Its own name" +is by default the name of the host it is running on, but this can be overriden +with the +.B -n +option (see "OPTIONS" below). Using the +.B -S +option (see "OPTIONS" below), it can also be instructed to respond with IP +information about other hosts, provided they are locatable via the +gethostbyname() call, or they are in a netbios hosts file. + +Nmbd can also be used as a WINS (Windows Internet Name Server) +server. It will do this automatically by default. What this basically +means is that it will respond to all name requests that it receives +that are not broadcasts, as long as it can resolve the name. +.SH OPTIONS +.B -B + +.RS 3 +On some systems, the server is unable to determine the broadcast address to +use for name registration requests. If your system has this difficulty, this +parameter may be used to specify an appropriate broadcast address. The +address should be given in standard "a.b.c.d" notation. + +Only use this parameter if you are sure that the server cannot properly +determine the proper broadcast address. + +The default broadcast address is determined by the server at run time. If it +encounters difficulty doing so, it makes a guess based on the local IP +number. +.RE +.B -I + +.RS 3 +On some systems, the server is unable to determine the correct IP +address to use. This allows you to override the default choice. +.RE + +.B -D + +.RS 3 +If specified, this parameter causes the server to operate as a daemon. That is, +it detaches itself and runs in the background, fielding requests on the +appropriate port. + +By default, the server will NOT operate as a daemon. +.RE + +.B -C comment string + +.RS 3 +This allows you to set the "comment string" that is shown next to the +machine name in browse listings. + +A %v will be replaced with the Samba version number. + +A %h will be replaced with the hostname. + +It defaults to "Samba %v". +.RE + +.B -G + +.RS 3 +This option allows you to specify a netbios group (also known as +lanmanager domain) that the server should be part of. You may include +several of these on the command line if you like. Alternatively you +can use the -H option to load a netbios hosts file containing domain names. + +At startup, unless the -R switch has been used, the server will +attempt to register all group names in the hosts file and on the +command line (from the -G option). + +The server will also respond to queries on this name. +.RE + +.B -H + +.RS 3 +It may be useful in some situations to be able to specify a list of +netbios names for which the server should send a reply if +queried. This option allows that. The syntax is similar to the +standard /etc/hosts file format, but has some extensions. + +The file contains three columns. Lines beginning with a # are ignored +as comments. The first column is an IP address, or a hostname. If it +is a hostname then it is interpreted as the IP address returned by +gethostbyname() when read. Any IP address of 0.0.0.0 will be +interpreted as the servers own IP address. + +The second column is a netbios name. This is the name that the server +will respond to. It must be less than 20 characters long. + +The third column is optional, and is intended for flags. Currently the +only flags supported are G, S and M. A G indicates that the name is a +group (also known as domain) name. + +At startup all groups known to the server (either from this file or +from the -G option) are registered on the network (unless the -R +option has been selected). + +A S or G means that the specified address is a broadcast address of a +network that you want people to be able to browse you from. Nmbd will +search for a master browser in that domain and will send host +announcements to that machine, informing it that the specifed somain +is available. + +A M means that this name is the default netbios name for this +machine. This has the same affect as specifying the -n option to nmbd. + +After startup the server waits for queries, and will answer queries to +any name known to it. This includes all names in the netbios hosts +file (if any), it's own name, and any names given with the -G option. + +The primary intention of the -H option is to allow a mapping from +netbios names to internet domain names, and to allow the specification +of groups that the server should be part of. + +.B Example: + + # This is a sample netbios hosts file + + # DO NOT USE THIS FILE AS-IS + # YOU MAY INCONVENIENCE THE OWNERS OF THESE IPs + # if you want to include a name with a space in it then + # use double quotes. + + # first put ourselves in the group LANGROUP + 0.0.0.0 LANGROUP G + + # next add a netbios alias for a faraway host + arvidsjaur.anu.edu.au ARVIDSJAUR + + # finally put in an IP for a hard to find host + 130.45.3.213 FREDDY + + # now we want another subnet to be able to browse + # us in the workgroup UNIXSERV + 192.0.2.255 UNIXSERV G + +.RE + +.B -M +.I workgroup name + +.RS 3 +If this parameter is given, the server will look for a master browser +for the specified workgroup name, report success or failure, then +exit. If successful, the IP address of the name located will be +reported. + +If you use the workgroup name "-" then nmbd will search for a master +browser for any workgroup by using the name __MSBROWSE__. + +This option is meant to be used interactively on the command line, not +as a daemon or in inetd. + +.RE +.B -N + +.RS 3 +On some systems, the server is unable to determine the netmask. If +your system has this difficulty, this parameter may be used to specify +an appropriate netmask. The mask should be given in standard +"a.b.c.d" notation. + +Only use this parameter if you are sure that the server cannot properly +determine the proper netmask. + +The default netmask is determined by the server at run time. If it +encounters difficulty doing so, it makes a guess based on the local IP +number. +.RE + +.B -d +.I debuglevel +.RS 3 + +debuglevel is an integer from 0 to 5. + +The default value if this parameter is not specified is zero. + +The higher this value, the more detail will be logged to the log files about +the activities of the server. At level 0, only critical errors and serious +warnings will be logged. Level 1 is a reasonable level for day to day running +- it generates a small amount of information about operations carried out. + +Levels above 1 will generate considerable amounts of log data, and should +only be used when investigating a problem. Levels above 3 are designed for +use only by developers and generate HUGE amounts of log data, most of which +is extremely cryptic. +.RE + +.B -l +.I log file + +.RS 3 +If specified, +.I logfile +specifies a base filename into which operational data from the running server +will be logged. + +The default base name is specified at compile time. + +The base name is used to generate actual log file names. For example, if the +name specified was "log", the following files would be used for log data: + +.RS 3 +log.nmb (containing debugging information) + +log.nmb.in (containing inbound transaction data) + +log.nmb.out (containing outbound transaction data) +.RE + +The log files generated are never removed by the server. +.RE +.RE + +.B -n +.I netbios name + +.RS 3 +This parameter tells the server what netbios name to respond with when +queried. The same name is also registered on startup unless the -R +parameter was specified. + +The default netbios name used if this parameter is not specified is the +name of the host on which the server is running. +.RE + +.B -p +.I port number +.RS 3 + +port number is a positive integer value. + +The default value if this parameter is not specified is 137. + +This number is the port number that will be used when making connections to +the server from client software. The standard (well-known) port number for the +server is 137, hence the default. If you wish to run the server as an ordinary +user rather than as root, most systems will require you to use a port number +greater than 1024 - ask your system administrator for help if you are in this +situation. + +Note that the name server uses UDP, not TCP! + +This parameter is not normally specified except in the above situation. +.RE +.SH FILES + +.B /etc/inetd.conf + +.RS 3 +If the server is to be run by the inetd meta-daemon, this file must contain +suitable startup information for the meta-daemon. See the section +"INSTALLATION" below. +.RE + +.B /etc/rc.d/rc.inet2 + +.RS 3 +(or whatever initialisation script your system uses) + +If running the server as a daemon at startup, this file will need to contain +an appropriate startup sequence for the server. See the section "Installation" +below. +.RE + +.B /etc/services + +.RS 3 +If running the server via the meta-daemon inetd, this file must contain a +mapping of service name (eg., netbios-ns) to service port (eg., 137) and +protocol type (eg., udp). See the section "INSTALLATION" below. +.RE +.RE + +.SH ENVIRONMENT VARIABLES +Not applicable. + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the server software be installed under the /usr/local +hierarchy, in a directory readable by all, writeable only by root. The server +program itself should be executable by all, as users may wish to run the +server themselves (in which case it will of course run with their privileges). +The server should NOT be setuid or setgid! + +The server log files should be put in a directory readable and writable only +by root, as the log files may contain sensitive information. + +The remaining notes will assume the following: + +.RS 3 +nmbd (the server program) installed in /usr/local/smb + +log files stored in /var/adm/smblogs +.RE + +The server may be run either as a daemon by users or at startup, or it may +be run from a meta-daemon such as inetd upon request. If run as a daemon, the +server will always be ready, so starting sessions will be faster. If run from +a meta-daemon some memory will be saved and utilities such as the tcpd +TCP-wrapper may be used for extra security. + +When you've decided, continue with either "Running the server as a daemon" or +"Running the server on request". +.SH RUNNING THE SERVER AS A DAEMON +To run the server as a daemon from the command line, simply put the "-D" option +on the command line. There is no need to place an ampersand at the end of the +command line - the "-D" option causes the server to detach itself from the +tty anyway. + +Any user can run the server as a daemon (execute permissions permitting, of +course). This is useful for testing purposes. + +To ensure that the server is run as a daemon whenever the machine is started, +you will need to modify the system startup files. Wherever appropriate (for +example, in /etc/rc.d/rc.inet2), insert the following line, substituting +values appropriate to your system: + +.RS 3 +/usr/local/smb/nmbd -D -l/var/adm/smblogs/log +.RE + +(The above should appear in your initialisation script as a single line. +Depending on your terminal characteristics, it may not appear that way in +this man page. If the above appears as more than one line, please treat any +newlines or indentation as a single space or TAB character.) + +If the options used at compile time are appropriate for your system, all +parameters except the desired debug level and "-D" may be omitted. See the +section on "Options" above. +.SH RUNNING THE SERVER ON REQUEST +If your system uses a meta-daemon such as inetd, you can arrange to have the +SMB name server started whenever a process attempts to connect to it. This +requires several changes to the startup files on the host machine. If you are +experimenting as an ordinary user rather than as root, you will need the +assistance of your system administrator to modify the system files. + +First, ensure that a port is configured in the file /etc/services. The +well-known port 137 should be used if possible, though any port may be used. + +Ensure that a line similar to the following is in /etc/services: + +.RS 3 +netbios-ns 137/udp +.RE + +Note for NIS/YP users: You may need to rebuild the NIS service maps rather +than alter your local /etc/services file. + +Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event +that you are using a meta-daemon other than inetd, you are on your own). Note +that the first item in this line matches the service name in /etc/services. +Substitute appropriate values for your system in this line (see +.B inetd(8)): + +.RS 3 +netbios-ns dgram udp wait root /usr/local/smb/nmbd -l/var/adm/smblogs/log +.RE + +(The above should appear in /etc/inetd.conf as a single line. Depending on +your terminal characteristics, it may not appear that way in this man page. +If the above appears as more than one line, please treat any newlines or +indentation as a single space or TAB character.) + +Note that there is no need to specify a port number here, even if you are +using a non-standard port number. +.SH TESTING THE INSTALLATION +If running the server as a daemon, execute it before proceeding. If +using a meta-daemon, either restart the system or kill and restart the +meta-daemon. Some versions of inetd will reread their configuration tables if +they receive a HUP signal. + +To test whether the name server is running, start up a client +.I on a different machine +and see whether the desired name is now present. Alternatively, run +the nameserver +.I on a different machine +specifying "-L netbiosname", where "netbiosname" is the name you have +configured the test server to respond with. The command should respond +with success, and the IP number of the machine using the specified netbios +name. You may need the -B parameter on some systems. See the README +file for more information on testing nmbd. + +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the server has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B inetd(8), +.B smbd(8), +.B smb.conf(5), +.B smbclient(1), +.B testparm(1), +.B testprns(1) + +.SH DIAGNOSTICS +[This section under construction] + +Most diagnostics issued by the server are logged in the specified log file. The +log file name is specified at compile time, but may be overridden on the +command line. + +The number and nature of diagnostics available depends on the debug level used +by the server. If you have problems, set the debug level to 3 and peruse the +log files. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. + +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +This man page written by Karl Auer (Karl.Auer@anu.edu.au) + +See +.B smb.conf(5) for a full list of contributors and details on how to +submit bug reports, comments etc. + + + + + diff --git a/docs/manpages/samba.7 b/docs/manpages/samba.7 new file mode 100644 index 0000000000..0c81f736b6 --- /dev/null +++ b/docs/manpages/samba.7 @@ -0,0 +1,190 @@ +.TH SAMBA 7 29/3/95 Samba Samba +.SH NAME +Samba \- a LanManager like fileserver for Unix +.SH SYNOPSIS +.B Samba +.SH DESCRIPTION +The +.B Samba +software suite is a collection of programs that implements the SMB +protocol for unix systems. This protocol is sometimes also referred to +as the LanManager or Netbios protocol. + +.SH COMPONENTS + +The Samba suite is made up of several components. Each component is +described in a separate manual page. It is strongly recommended that +you read the documentation that comes with Samba and the manual pages +of those components that you use. If the manual pages aren't clear +enough then please send me a patch! + +The smbd(8) daemon provides the file and print services to SMB clents, +such as Windows for Workgroups, Windows NT or LanManager. The +configuration file for this daemon is described in smb.conf(5). + +The nmbd(8) daemon provides Netbios nameserving and browsing +support. It can also be run interactively to query other name service +daemons. + +The smbclient(1) program implements a simple ftp-like client. This is +useful for accessing SMB shares on other compatible servers (such as +WfWg), and can also be used to allow a unix box to print to a printer +attached to any SMB server (such as a PC running WfWg). + +The testparm(1) utility allows you to test your smb.conf(5) +configuration file. + +The smbstatus(1) utility allows you to tell who is currently using the +smbd(8) server. + +.SH AVAILABILITY + +The Samba software suite is licensed under the Gnu Public License. A +copy of that license should have come with the package. You are +encouraged to distribute copies of the Samba suite, but please keep it +intact. + +The latest version of the Samba suite can be obtained via anonymous +ftp from nimbus.anu.edu.au in the directory pub/tridge/samba/. It is +also available on several mirror sites worldwide. + +You may also find useful information about Samba on the newsgroup +comp.protocols.smb and the Samba mailing list. Details on how to join +the mailing list are given in the README file that comes with Samba. + +If you have access to a WWW viewer (such as Netscape or Mosaic) then +you will also find lots of useful information, including back issues +of the Samba mailing list, at http://lake.canberra.edu.au/pub/samba/ + +.SH AUTHOR + +The main author of the Samba suite is Andrew Tridgell. He may be +contacted via e-mail at samba-bugs@anu.edu.au. + +There have also been an enourmous number of contributors to Samba from +all over the world. A partial list of these contributors is included +in the CREDITS section below. The list is, however, badly out of +date. More up to date info may be obtained from the change-log that +comes with the Samba source code. + +.SH CONTRIBUTIONS + +If you wish to contribute to the Samba project, then I suggest you +join the Samba mailing list. + +If you have patches to submit or bugs to report then you may mail them +directly to samba-bugs@anu.edu.au. Note, however, that due to the +enourmous popularity of this package I may take some time to repond to +mail. I prefer patches in "diff -u" format. + +.SH CREDITS + +Contributors to the project are (in alphabetical order by email address): + +(NOTE: This list is very out of date) + + Adams, Graham + (gadams@ddrive.demon.co.uk) + Allison, Jeremy + (jeremy@netcom.com) + Andrus, Ross + (ross@augie.insci.com) + Auer, Karl + (Karl.Auer@anu.edu.au) + Bogstad, Bill + (bogstad@cs.jhu.edu) + Boreham, Bryan + (Bryan@alex.com) + Boreham, David + (davidb@ndl.co.uk) + Butler, Michael + (imb@asstdc.scgt.oz.au) + ??? + (charlie@edina.demon.co.uk) + Chua, Michael + (lpc@solomon.technet.sg) + Cochran, Marc + (mcochran@wellfleet.com) + Dey, Martin N + (mnd@netmgrs.co.uk) + Errath, Maximilian + (errath@balu.kfunigraz.ac.at) + Fisher, Lee + (leefi@microsoft.com) + Foderaro, Sean + (jkf@frisky.Franz.COM) + Greer, Brad + (brad@cac.washington.edu) + Griffith, Michael A + (grif@cs.ucr.edu) + Grosen, Mark + (MDGrosen@spectron.COM) + ???? + (gunjkoa@dep.sa.gov.au) + Haapanen, Tom + (tomh@metrics.com) + Hench, Mike + (hench@cae.uwm.edu) + Horstman, Mark A + (mh2620@sarek.sbc.com) + Hudson, Tim + (tim.hudson@gslmail.mincom.oz.au) + Hulthen, Erik Magnus + (magnus@axiom.se) + ??? + (imb@asstdc.scgt.oz.au) + Iversen, Per Steinar + (iversen@dsfys1.fi.uib.no) + Kaara, Pasi + (ppk@atk.tpo.fi) + Karman, Merik + (merik@blackadder.dsh.oz.au) + Kiff, Martin + (mgk@newton.npl.co.uk) + Kiick, Chris + (cjkiick@flinx.b11.ingr.com) + Kukulies, Christoph + (kuku@acds.physik.rwth-aachen.de) + ??? + (lance@fox.com) + Lendecke, Volker + (lendecke@namu01.gwdg.de) + ??? + (lonnie@itg.ti.com) + Mahoney, Paul Thomas + (ptm@xact1.xact.com) + Mauelshagen, Heinz + (mauelsha@ez.da.telekom.de) + Merrick, Barry G + (bgm@atml.co.uk) + Mol, Marcel + (marcel@fanout.et.tudeflt.nl) + ??? + (njw@cpsg.com.au) + ??? + (noses@oink.rhein.de) + Owens, John + (john@micros.com) + Pierson, Jacques + (pierson@ketje.enet.dec.com) + Powell, Mark + (mark@scot1.ucsalf.ac.uk) + Reiz, Steven + (sreiz@aie.nl) + Schlaeger, Joerg + (joergs@toppoint.de) + S{rkel{, Vesa + (vesku@rankki.kcl.fi) + Tridgell, Andrew + (samba-bugs@anu.edu.au) + Troyer, Dean + (troyer@saifr00.ateng.az.honeywell.com) + Wakelin, Ross + (rossw@march.co.uk) + Wessels, Stefan + (SWESSELS@dos-lan.cs.up.ac.za) + Young, Ian A + (iay@threel.co.uk) + van der Zwan, Paul + (paulzn@olivetti.nl) + diff --git a/docs/manpages/smb.conf.5 b/docs/manpages/smb.conf.5 new file mode 100644 index 0000000000..933d71ff0c --- /dev/null +++ b/docs/manpages/smb.conf.5 @@ -0,0 +1,2719 @@ +.TH SMB.CONF 5 11/10/94 smb.conf smb.conf +.SH NAME +smb.conf \- configuration file for smbd +.SH SYNOPSIS +.B smb.conf +.SH DESCRIPTION +The +.B smb.conf +file is a configuration file for the Samba suite. + +.B smb.conf +contains runtime configuration information for the +.B smbd +program. The +.B smbd +program provides LanManager-like services to clients +using the SMB protocol. + +.SH FILE FORMAT +The file consists of sections and parameters. A section begins with the +name of the section in square brackets and continues until the next +section begins. Sections contain parameters of the form 'name = value'. + +The file is line-based - that is, each newline-terminated line represents +either a comment, a section name or a parameter. + +Section and parameter names are not case sensitive. + +Only the first equals sign in a parameter is significant. Whitespace before +or after the first equals sign is discarded. Leading, trailing and internal +whitespace in section and parameter names is irrelevant. Leading and +trailing whitespace in a parameter value is discarded. Internal whitespace +within a parameter value is retained verbatim. + +Any line beginning with a semicolon is ignored, as are lines containing +only whitespace. + +Any line ending in a \\ is "continued" on the next line in the +customary unix fashion. + +The values following the equals sign in parameters are all either a string +(no quotes needed) or a boolean, which may be given as yes/no, 0/1 or +true/false. Case is not significant in boolean values, but is preserved +in string values. Some items such as create modes are numeric. +.SH SERVICE DESCRIPTIONS +Each section in the configuration file describes a service. The section name +is the service name and the parameters within the section define the service's +attributes. + +There are three special sections, [global], [homes] and [printers], which are +described under 'special sections'. The following notes apply to ordinary +service descriptions. + +A service consists of a directory to which access is being given plus a +description of the access rights which are granted to the user of the +service. Some housekeeping options are also specifiable. + +Services are either filespace services (used by the client as an extension of +their native file systems) or printable services (used by the client to access +print services on the host running the server). + +Services may be guest services, in which case no password is required to +access them. A specified guest account is used to define access privileges +in this case. + +Services other than guest services will require a password to access +them. The client provides the username. As many clients only provide +passwords and not usernames, you may specify a list of usernames to +check against the password using the "user=" option in the service +definition. + +Note that the access rights granted by the server are masked by the access +rights granted to the specified or guest user by the host system. The +server does not grant more access than the host system grants. + +The following sample section defines a file space service. The user has write +access to the path /home/bar. The service is accessed via the service name +"foo": + + [foo] + path = /home/bar + writable = true + +The following sample section defines a printable service. The service is +readonly, but printable. That is, the only write access permitted is via +calls to open, write to and close a spool file. The 'guest ok' parameter +means access will be permitted as the default guest user (specified elsewhere): + + [aprinter] + path = /usr/spool/public + read only = true + printable = true + public = true + +.SH SPECIAL SECTIONS + +.SS The [global] section +.RS 3 +Parameters in this section apply to the server as a whole, or are defaults +for services which do not specifically define certain items. See the notes +under 'Parameters' for more information. +.RE + +.SS The [homes] section +.RS 3 +If a section called 'homes' is included in the configuration file, services +connecting clients to their home directories can be created on the fly by the +server. + +When the connection request is made, the existing services are scanned. If a +match is found, it is used. If no match is found, the requested service name is +treated as a user name and looked up in the local passwords file. If the +name exists and the correct password has been given, a service is created +by cloning the [homes] section. + +Some modifications are then made to the newly created section: + +.RS 3 +The service name is changed from 'homes' to the located username + +If no path was given, the path is set to the user's home directory. +.RE + +If you decide to use a path= line in your [homes] section then you may +find it useful to use the %S macro. For example path=/data/pchome/%S +would be useful if you have different home directories for your PCs +than for unix access. + +This is a fast and simple way to give a large number of clients access to +their home directories with a minimum of fuss. + +A similar process occurs if the requested service name is "homes", except that +the service name is not changed to that of the requesting user. This method +of using the [homes] section works well if different users share a client PC. + +The [homes] section can specify all the parameters a normal service section +can specify, though some make more sense than others. The following is a +typical and suitable [homes] section: + + [homes] + writable = yes + +An important point: + +.RS 3 +If guest access is specified in the [homes] section, all home directories will +be accessible to all clients +.B without a password. +In the very unlikely event +that this is actually desirable, it would be wise to also specify read only +access. +.RE +.RE + +Note that the browseable flag for auto home directories will be +inherited from the global browseable flag, not the [homes] browseable +flag. This is useful as it means setting browseable=no in the [homes] +section will hide the [homes] service but make any auto home +directories visible. + +.SS The [printers] section +.RS 3 +This section works like [homes], but for printers. + +If a [printers] section occurs in the configuration file, users are able +to connect to any printer specified in the local host's printcap file. + +When a connection request is made, the existing services are scanned. If a +match is found, it is used. If no match is found, but a [homes] section +exists, it is used as described above. Otherwise, the requested service name is +treated as a printer name and the appropriate printcap file is scanned to +see if the requested service name is a valid printer name. If a match is +found, a new service is created by cloning the [printers] section. + +A few modifications are then made to the newly created section: + +.RS 3 +The service name is set to the located printer name + +If no printer name was given, the printer name is set to the located printer +name + +If the service does not permit guest access and no username was given, the +username is set to the located printer name. +.RE + +Note that the [printers] service MUST be printable - if you specify otherwise, +the server will refuse to load the configuration file. + +Typically the path specified would be that of a world-writable spool directory +with the sticky bit set on it. A typical [printers] entry would look like this: + + [printers] + path = /usr/spool/public + writable = no + public = yes + printable = yes + +All aliases given for a printer in the printcap file are legitimate printer +names as far as the server is concerned. If your printing subsystem doesn't +work like that, you will have to set up a pseudo-printcap. This is a file +consisting of one or more lines like this: + + alias|alias|alias|alias... + +Each alias should be an acceptable printer name for your printing +subsystem. In the [global] section, specify the new file as your printcap. +The server will then only recognise names found in your pseudo-printcap, +which of course can contain whatever aliases you like. The same technique +could be used simply to limit access to a subset of your local printers. + +An alias, by the way, is defined as any component of the first entry of a +printcap record. Records are separated by newlines, components (if there are +more than one) are separated by vertical bar symbols ("|"). +.SH PARAMETERS +Parameters define the specific attributes of services. + +Some parameters are specific to the [global] section (eg., security). +Some parameters are usable in all sections (eg., create mode). All others are +permissible only in normal sections. For the purposes of the following +descriptions the [homes] and [printers] sections will be considered normal. +The letter 'G' in parentheses indicates that a parameter is specific to the +[global] section. The letter 'S' indicates that a parameter can be +specified in a secvice specific section. Note that all S parameters +can also be specified in the [global] section - in which case they +will define the default behaviour for all services. + +Parameters are arranged here in alphabetical order - this may not create +best bedfellows, but at least you can find them! Where there are synonyms, +the preferred synonym is described, others refer to the preferred synonym. + +.SS VARIABLE SUBSTITUTIONS + +Many of the strings that are settable in the config file can take +substitutions. For example the option "path = /tmp/%u" would be +interpreted as "path = /tmp/john" if the user connected with the +username john. + +These substitutions are mostly noted in the descriptions below, but +there are some general substitions which apply whenever they might be +relevant. These are: + +%S = the name of the current service, if any + +%P = the root directory of the current service, if any + +%u = user name of the current service, if any + +%g = primary group name of %u + +%U = session user name (the user name that the client wanted, not +necessarily the same as the one they got) + +%G = primary group name of %U + +%H = the home directory of the user given by %u + +%v = the Samba version + +%h = the hostname that Samba is running on + +%m = the netbios name of the client machine (very useful) + +%L = the netbios name of the server. This allows you to change your +config based on what the client calls you. Your server can have a "dual +personality". + +%M = the internet name of the client machine + +%d = The process id of the current server process + +%a = the architecture of the remote machine. Only some are recognised, +and those may not be 100% reliable. It currently recognises Samba, +WfWg, WinNT and Win95. Anything else will be known as "UNKNOWN". If it +gets it wrong then sending me a level 3 log should allow me to fix it. + +%I = The IP address of the client machine + +%T = the current date and time + +There are some quite creative things that can be done with these +substitutions and other smb.conf options. + +.SS NAME MANGLING + +Samba supports "name mangling" so that Dos and Windows clients can use +files that don't conform to the 8.3 format. It can also be set to adjust +the case of 8.3 format filenames. + +There are several options that control the way mangling is performed, +and they are grouped here rather than listed separately. For the +defaults look at the output of the testparm program. + +All of these options can be set separately for each service (or +globally, of course). + +The options are: + +"mangle case = yes/no" controls if names that have characters that +aren't of the "default" case are mangled. For example, if this is yes +then a name like "Mail" would be mangled. Default no. + +"case sensitive = yes/no" controls whether filenames are case +sensitive. If they aren't then Samba must do a filename search and +match on passed names. Default no. + +"default case = upper/lower" controls what the default case is for new +filenames. Default lower. + +"preserve case = yes/no" controls if new files are created with the +case that the client passes, or if they are forced to be the "default" +case. Default no. + +"short preserve case = yes/no" controls if new files which conform to 8.3 +syntax, that is all in upper case and of suitable length, are created +upper case, or if they are forced to be the "default" case. This option can +be use with "preserve case = yes" to permit long filenames to retain their +case, while short names are lowered. Default no. + +.SS COMPLETE LIST OF GLOBAL PARAMETER + +Here is a list of all global parameters. See the section of each +parameter for details. Note that some are synonyms. + +auto services + +config file + +deadtime + +debuglevel + +default + +default service + +dfree command + +encrypt passwords + +getwd cache + +hosts equiv + +include + +keepalive + +lock dir + +load printers + +lock directory + +log file + +log level + +lpq cache time + +mangled stack + +max log size + +max packet + +max xmit + +message command + +null passwords + +os level + +packet size + +passwd chat + +passwd program + +password level + +password server + +preferred master + +preload + +printing + +printcap name + +protocol + +read bmpx + +read prediction + +read raw + +read size + +root + +root dir + +root directory + +security + +server string + +smbrun + +socket options + +status + +strip dot + +time offset + +username map + +use rhosts + +valid chars + +workgroup + +write raw + +.SS COMPLETE LIST OF SERVICE PARAMETER + +Here is a list of all service parameters. See the section of each +parameter for details. Note that some are synonyms. + +admin users + +allow hosts + +alternate permissions + +available + +browseable + +case sensitive + +case sig names + +copy + +create mask + +create mode + +comment + +default case + +deny hosts + +directory + +dont descend + +exec + +force group + +force user + +guest account + +guest ok + +guest only + +hide dot files + +hosts allow + +hosts deny + +invalid users + +locking + +lppause command + +lpq command + +lpresume command + +lprm command + +magic output + +magic script + +mangle case + +mangled names + +mangling char + +map archive + +map hidden + +map system + +max connections + +min print space + +only guest + +only user + +path + +postexec + +postscript + +preserve case + +print command + +print ok + +printable + +printer + +printer name + +public + +read only + +read list + +revalidate + +root postexec + +root preexec + +set directory + +share modes + +short preserve case + +strict locking + +sync always + +user + +username + +users + +valid users + +volume + +wide links + +writable + +write ok + +writeable + +write list + +.SS EXPLANATION OF EACH PARAMETER +.RS 3 + +.SS admin users (G) + +This is a list of users who will be granted administrative privilages +on the share. This means that they will do all file operations as the +super-user (root). + +You should use this option very carefully, as any user in this list +will be able to do anything they like on the share, irrespective of +file permissions. + +.B Default: + no admin users + +.B Example: + admin users = jason + +.SS auto services (G) +This is a list of services that you want to be automatically added to +the browse lists. This is most useful for homes and printers services +that would otherwise not be visible. + +Note that if you just want all printers in your printcap file loaded +then the "load printers" option is easier. + +.B Default: + no auto services + +.B Example: + auto services = fred lp colorlp + + +.SS allow hosts (S) +A synonym for this parameter is 'hosts allow'. + +This parameter is a comma delimited set of hosts which are permitted to access +a services. If specified in the [global] section, matching hosts will be +allowed access to any service that does not specifically exclude them from +access. Specific services my have their own list, which override those +specified in the [global] section. + +You can specify the hosts by name or IP number. For example, you could +restrict access to only the hosts on a Class C subnet with something like +"allow hosts = 150.203.5.". The full syntax of the list is described in +the man page +.B hosts_access(5). + +You can also specify hosts by network/netmask pairs and by netgroup +names if your system supports netgroups. The EXCEPT keyword can also +be used to limit a wildcard list. The following examples may provide +some help: + +Example 1: allow all IPs in 150.203.*.* except one + + hosts allow = 150.203. EXCEPT 150.203.6.66 + +Example 2: allow hosts that match the given network/netmask + + hosts allow = 150.203.15.0/255.255.255.0 + +Example 3: allow a couple of hosts + + hosts allow = lapland, arvidsjaur + +Example 4: allow only hosts in netgroup "foonet" or localhost, but +deny access from one particular host + + hosts allow = @foonet, localhost + hosts deny = pirate + +Note that access still requires suitable user-level passwords. + +See testparm(1) for a way of testing your host access to see if it +does what you expect. + +.B Default: + none (ie., all hosts permitted access) + +.B Example: + allow hosts = 150.203.5. myhost.mynet.edu.au + +.SS alternate permissions (S) + +This option affects the way the "read only" DOS attribute is produced +for unix files. If this is false then the read only bit is set for +files on writeable shares which the user cannot write to. + +If this is true then it is set for files whos user write bit is not set. + +The latter behaviour of useful for when users copy files from each +others directories, and use a file manager that preserves +permissions. Without this option they may get annoyed as all copied +files will have the "read only" bit set. + +.B Default: + alternate permissions = no + +.B Example: + alternate permissions = yes + +.SS available (S) +This parameter lets you 'turn off' a service. If 'available = no', then +ALL attempts to connect to the service will fail. Such failures are logged. + +.B Default: + available = yes + +.B Example: + available = no +.SS browseable (S) +This controls whether this share is seen in the list of available +shares in a net view and in the browse list. + +.B Default: + browseable = Yes + +.B Example: + browseable = No + +.SS case sig names (G) +See "case sensitive" + +.SS comment (S) +This is a text field that is seen when a client does a net view to +list what shares are available. It will also be used when browsing is +fully supported. + +.B Default: + No comment string + +.B Example: + comment = Fred's Files + +.SS config file (G) + +This allows you to override the config file to use, instead of the +default (usually smb.conf). There is a chicken and egg problem here as +this option is set in the config file! + +For this reason, if the name of the config file has changed when the +parameters are loaded then it will reload them from the new config +file. + +This option takes the usual substitutions, which can be very useful. + +If thew config file doesn't exist then it won't be loaded (allowing +you to special case the config files of just a few clients). + +.B Example: + config file = /usr/local/samba/smb.conf.%m + +.SS copy (S) +This parameter allows you to 'clone' service entries. The specified +service is simply duplicated under the current service's name. Any +parameters specified in the current section will override those in the +section being copied. + +This feature lets you set up a 'template' service and create similar +services easily. Note that the service being copied must occur earlier +in the configuration file than the service doing the copying. + +.B Default: + none + +.B Example: + copy = otherservice +.SS create mask (S) +A synonym for this parameter is 'create mode'. + +This parameter is the octal modes which are used when converting DOS modes +to Unix modes. + +Note that Samba will or this value with 0700 as you must have at least +user read, write and execute for Samba to work properly. + +.B Default: + create mask = 0755 + +.B Example: + create mask = 0775 +.SS create mode (S) +See +.B create mask. +.SS dead time (G) +The value of the parameter (a decimal integer) represents the number of +minutes of inactivity before a connection is considered dead, and it +is disconnected. The deadtime only takes effect if the number of open files +is zero. + +This is useful to stop a server's resources being exhausted by a large +number of inactive connections. + +Most clients have an auto-reconnect feature when a connection is broken so +in most cases this parameter should be transparent to users. + +Using this parameter with a timeout of a few minutes is recommended +for most systems. + +A deadtime of zero indicates that no auto-disconnection should be performed. + +.B Default: + dead time = 0 + +.B Example: + dead time = 15 +.SS debug level (G) +The value of the parameter (an integer) allows the debug level +(logging level) to be specified in the smb.conf file. This is to give +greater flexibility in the configuration of the system. + +The default will be the debug level specified on the command line. + +.B Example: + debug level = 3 +.SS default (G) +See +.B default service. +.SS default case (S) + +See the section on "NAME MANGLING" Also note the addition of "short +preserve case" + +.SS default service (G) +A synonym for this parameter is 'default'. + +This parameter specifies the name of a service which will be connected to +if the service actually requested cannot be found. Note that the square +brackets are NOT given in the parameter value (see example below). + +There is no default value for this parameter. If this parameter is not given, +attempting to connect to a nonexistent service results in an error. + +Typically the default service would be a public, read-only service. + +Also not that s of 1.9.14 the apparent service name will be changed to +equal that of the requested service, this is very useful as it allows +you to use macros like %S to make a wildcard service. + +Note also that any _ characters in the name of the service used in the +default service will get mapped to a /. This allows for interesting +things. + + +.B Example: + default service = pub + + [pub] + path = /%S + + +.SS deny hosts (S) +A synonym for this parameter is 'hosts deny'. + +The opposite of 'allow hosts' - hosts listed here are NOT permitted +access to services unless the specific services have their own lists to +override this one. Where the lists conflict, the 'allow' list takes precedence. + +.B Default: + none (ie., no hosts specifically excluded) + +.B Example: + deny hosts = 150.203.4. badhost.mynet.edu.au +.SS dfree command (G) +The dfree command setting should only be used on systems where a +problem occurs with the internal disk space calculations. This has +been known to happen with Ultrix, but may occur with other operating +systems. The symptom that was seen was an error of "Abort Retry +Ignore" at the end of each directory listing. + +This setting allows the replacement of the internal routines to +calculate the total disk space and amount available with an external +routine. The example below gives a possible script that might fulfill +this function. + +The external program will be passed a single parameter indicating a +directory in the filesystem being queried. This will typically consist +of the string "./". The script should return two integers in ascii. The +first should be the total disk space in blocks, and the second should +be the number of available blocks. An optional third return value +can give the block size in bytes. The default blocksize is 1024 bytes. + +Note: Your script should NOT be setuid or setgid and should be owned by +(and writable only by) root! + +.B Default: + By default internal routines for determining the disk capacity +and remaining space will be used. + +.B Example: + dfree command = /usr/local/smb/dfree + + Where the script dfree (which must be made executable) could be + + #!/bin/sh + df $1 | tail -1 | awk '{print $2" "$4}' + + or perhaps (on Sys V) + + #!/bin/sh + /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' + + + Note that you may have to replace the command names with full +path names on some systems. +.SS directory (S) +See +.B path. +.SS dont descend (S) +There are certain directories on some systems (eg., the /proc tree under +Linux) that are either not of interest to clients or are infinitely deep +(recursive). This parameter allows you to specify a comma-delimited list +of directories that the server should always show as empty. + +Note that Samba can be very fussy about the exact format of the "dont +descend" entries. For example you ma need "./proc" instead of just +"/proc". Experimentation is the best policy :-) + +.B Default: + none (ie., all directories are OK to descend) + +.B Example: + dont descend = /proc,/dev + +.SS encrypt passwords (G) + +This boolean controls whether encrypted passwords will be negotiated +with the cient. Note that this option has no effect if you haven't +compiled in the necessary des libraries and encryption code. It +defaults to no. + +.SS exec (S) + +This is an alias for preexec + + +.SS force group (S) +This specifies a group name that all connections to this service +should be made as. This may be useful for sharing files. + +.B Default: + no forced group + +.B Example: + force group = agroup + +.SS force user (S) +This specifies a user name that all connections to this service +should be made as. This may be useful for sharing files. You should +also use it carefully as using it incorrectly can cause security +problems. + +This user name only gets used once a connection is established. Thus +clients still need to connect as a valid user and supply a valid +password. Once connected, all file operations will be performed as the +"forced user", not matter what username the client connected as. + +.B Default: + no forced user + +.B Example: + force user = auser + +.SS guest account (S) +This is a username which will be used for access to services which are +specified as 'guest ok' (see below). Whatever privileges this user has +will be available to any client connecting to the guest +service. Typically this user will exist in the password file, but will +not have a valid login. If a username is specified in a given service, +the specified username overrides this one. + +One some systems the account "nobody" may not be able to print. Use +another account in this case. You should test this by trying to log in +as your guest user (perhaps by using the "su -" command) and trying to +print using lpr. + +Note that as of version 1.9 of Samba this option may be set +differently for each service. + +.B Default: + specified at compile time + +.B Example: + guest account = nobody +.SS getwd cache (G) +This is a tuning option. When this is enabled a cacheing algorithm will +be used to reduce the time taken for getwd() calls. This can have a +significant impact on performance, especially when widelinks is False. + +.B Default: + getwd cache = No + +.B Example: + getwd cache = Yes +.SS guest ok (S) +See +.B public. +.SS guest only (S) +If this parameter is 'yes' for a service, then only guest connections to the +service are permitted. This parameter will have no affect if "guest ok" or +"public" is not set for the service. + +See the section below on user/password validation for more information about +this option. + +.B Default: + guest only = no + +.B Example: + guest only = yes +.SS hide dot files (S) +This is a boolean parameter that controls whether files starting with +a dot appear as hidden files. + +.B Default: + hide dot files = yes + +.B Example: + hide dot files = no +.SS hosts allow (S) +See +.B allow hosts. +.SS hosts deny (S) +See +.B deny hosts. + +.SS group (S) +This is an alias for "force group" and is only kept for compatability +with old versions of Samba. It may be removed in future versions. + +.SS hosts equiv (G) +If this global parameter is a non-null string, it specifies the name of +a file to read for the names of hosts and users who will be allowed access +without specifying a password. + +This is not be confused with +.B allow hosts +which is about hosts access to services and is more useful for guest services. +.B hosts equiv +may be useful for NT clients which will not supply passwords to samba. + +NOTE: The use of hosts.equiv can be a major security hole. This is +because you are trusting the PC to supply the correct username. It is +very easy to get a PC to supply a false username. I recommend that the +hosts.equiv option be only used if you really know what you are doing, +or perhaps on a home network where you trust your wife and kids :-) + +.B Default + No host equivalences + +.B Example + hosts equiv = /etc/hosts.equiv + +.SS invalid users (S) +This is a list of users that should not be allowed to login to this +service. This is really a "paranoid" check to absolutely ensure an +improper setting does not breach your security. + +A name starting with @ is interpreted as a unix group. + +The current servicename is substituted for %S. This is useful in the +[homes] section. + +See also "valid users" + +.B Default + No invalid users + +.B Example + invalid users = root fred admin @wheel + +.SS include (G) + +This allows you to inlcude one config file inside another. the file is +included literally, as though typed in place. + +It takes the standard substitutions, except %u, %P and %S + +.SS keep alive (G) +The value of the parameter (an integer) represents the number of seconds +between 'keepalive' packets. If this parameter is zero, no keepalive packets +will be sent. Keepalive packets, if sent, allow the server to tell whether a +client is still present and responding. + +Keepalives should, in general, not be needed if the socket being used +has the SO_KEEPALIVE attribute set on it (see "socket +options"). Basically you should only use this option if you strike +difficulties. + +.B Default: + keep alive = 0 + +.B Example: + keep alive = 60 +.SS load printers (G) +A boolean variable that controls whether all printers in the printcap +will be loaded for browsing by default. + +.B Default: + load printers = no + +.B Example: + load printers = yes + +.SS lock directory (G) +This options specifies the directory where lock files will be placed. +The lock files are used to implement the "max connections" option. + +.B Default: + lock directory = /tmp/samba + +.B Example: + lock directory = /usr/local/samba/locks +.SS locking (S) +This controls whether or not locking will be performed by the server in +response to lock requests from the client. + +If "locking = no", all lock and unlock requests will appear to succeed and +all lock queries will indicate that the queried lock is clear. + +If "locking = yes", real locking will be performed by the server. + +This option may be particularly useful for read-only filesystems which +do not need locking (such as cdrom drives). + +Be careful about disabling locking either globally or in a specific +service, as lack of locking may result in data corruption. + +.B Default: + locking = yes + +.B Example: + locking = no + +.SS log file (G) + +This options allows you to override the name of the Samba log file +(also known as the debug file). + +This option takes the standard substitutions, allowing you to have +separate log files for each user or machine. + +.B Example: + log file = /usr/local/samba/log.%m + +.SS log level (G) +see "debug level" + +.SS lppause command (S) +This parameter specifies the command to be executed on the server host in +order to stop printing or spooling a specific print job. + +This command should be a program or script which takes a printer name and +job number to pause the print job. Currently I don't know of any print +spooler system that can do this with a simple option, except for the PPR +system from Trinity College (ppr\-dist.trincoll.edu/pub/ppr). One way +of implementing this is by using job priorities, where jobs having a too +low priority wont be sent to the printer. See also the lppause command. + +If a %p is given then the printername is put in it's place. A %j is +replaced with the job number (an integer). +On HPUX (see printing=hpux), if the -p%p option is added to the lpq +command, the job will show up with the correct status, i.e. if the job +priority is lower than the set fence priority it will have the PAUSED +status, whereas if the priority is equal or higher it will have the +SPOOLED or PRINTING status. + +Note that it is good practice to include the absolute path in the lppause +command as the PATH may not be available to the server. + +.B Default: + Currently no default value is given to this string + +.B Example for HPUX: + lppause command = /usr/bin/lpalt %p-%j -p0 + +.SS lpq cache time (G) + +This controls how long lpq info will be cached for to prevent the lpq +command being called too often. A separate cache is kept for each +variation of the lpq command used by the system, so if you use +different lpq commands for different users then they won't share cache +information. + +The cache files are stored in /tmp/lpq.xxxx where xxxx is a hash +of the lpq command in use. + +The default is 10 seconds, meaning that the cached results of a +previous identical lpq command will be used if the cached data is less +than 10 seconds old. A large value may be advisable if your lpq +command is very slow. + +A value of 0 will disable cacheing completely. + +.B Default: + lpq cache time = 10 + +.B Example: + lpq cache time = 30 + +.SS lpq command (S) +This parameter specifies the command to be executed on the server host in +order to obtain "lpq"-style printer status information. + +This command should be a program or script which takes a printer name +as its only parameter and outputs printer status information. + +Currently four styles of printer status information are supported; +BSD, SYSV, AIX and HPUX. This covers most unix systems. You control +which type is expected using the "printing =" option. + +Some clients (notably Windows for Workgroups) may not correctly send the +connection number for the printer they are requesting status information +about. To get around this, the server reports on the first printer service +connected to by the client. This only happens if the connection number sent +is invalid. + +If a %p is given then the printername is put in it's place. Otherwise +it is placed at the end of the command. + +Note that it is good practice to include the absolute path in the lpq +command as the PATH may not be available to the server. + +.B Default: + depends on the setting of "printing =" + +.B Example: + lpq command = /usr/bin/lpq %p + +.SS lpresume command (S) +This parameter specifies the command to be executed on the server host in +order to restart or continue printing or spooling a specific print job. + +This command should be a program or script which takes a printer name and +job number to resume the print job. See also the lppause command. + +If a %p is given then the printername is put in it's place. A %j is +replaced with the job number (an integer). + +Note that it is good practice to include the absolute path in the lpresume +command as the PATH may not be available to the server. + +.B Default: + Currently no default value is given to this string + +.B Example for HPUX: + lpresume command = /usr/bin/lpalt %p-%j -p2 + +.SS lprm command (S) +This parameter specifies the command to be executed on the server host in +order to delete a print job. + +This command should be a program or script which takes a printer name +and job number, and deletes the print job. + +Currently four styles of printer control are supported; BSD, SYSV, AIX +and HPUX. This covers most unix systems. You control which type is +expected using the "printing =" option. + +If a %p is given then the printername is put in it's place. A %j is +replaced with the job number (an integer). + +Note that it is good practice to include the absolute path in the lprm +command as the PATH may not be available to the server. + +.B Default: + depends on the setting of "printing =" + +.B Example 1: + lprm command = /usr/bin/lprm -P%p %j + +.B Example 2: + lprm command = /usr/bin/cancel %p-%j + +.SS magic output (S) +This parameter specifies the name of a file which will contain output +created by a magic script (see +.I magic script +below). + +Warning: If two clients use the same magic script in the same directory the +output file content is undefined. +.B Default: + magic output = .out + +.B Example: + magic output = myfile.txt +.SS magic script (S) +This parameter specifies the name of a file which, if opened, will be +executed by the server when the file is closed. This allows a Unix script +to be sent to the Samba host and executed on behalf of the connected user. + +Scripts executed in this way will be deleted upon completion, permissions +permitting. + +If the script generates output, output will be sent to the file specified by +the +.I magic output +parameter (see above). + +Note that some shells are unable to interpret scripts containing +carriage-return-linefeed instead of linefeed as the end-of-line +marker. Magic scripts must be executable "as is" on the host, which +for some hosts and some shells will require filtering at the DOS end. + +Magic scripts are EXPERIMENTAL and should NOT be relied upon. +.B Default: + None. Magic scripts disabled. + +.B Example: + magic script = user.csh +.SS mangled map (S) +This is for those who want to directly map UNIX file names which are +not representable on DOS. The mangling of names is not always what is +needed. In particular you may have documents with file extensiosn +that differ between dos and unix. For example, under unix it is common +to use .html for HTML files, whereas under dos .htm is more commonly +used. + +So to map 'html' to 'htm' you put: + + mangled map = (*.html *.htm) + +One very useful case is to remove the annoying ;1 off the ends of +filenames on some CDROMS (only visible under some unixes). To do this +use a map of (*;1 *) + +.B default: + no mangled map + +.B Example: + mangled map = (*;1 *) + +.SS mangle case (S) + +See the section on "NAME MANGLING" + +.SS mangled names (S) +This controls whether non-DOS names under Unix should be mapped to +DOS-compatible names ("mangled") and made visible, or whether non-DOS names +should simply be ignored. + +See the section on "NAME MANGLING" for details on how to control the +mangling process. + +If mangling is used then the mangling algorithm is as follows: +.RS +- the first (up to) five alphanumeric characters before the rightmost dot of +the filename are preserved, forced to upper case, and appear as the first (up +to) five characters of the mangled name. + +- a tilde ("~") is appended to the first part of the mangled name, followed +by a two-character unique sequence, based on the origonal root name +(i.e., the original filename minus its final extension). The final +extension is included in the hash calculation only if it contains any upper +case characters or is longer than three characters. + +Note that the character to use may be specified using the "mangling +char" option, if you don't like ~. + +- the first three alphanumeric characters of the final extension are preserved, +forced to upper case and appear as the extension of the mangled name. The +final extension is defined as that part of the original filename after the +rightmost dot. If there are no dots in the filename, the mangled name will +have no extension (except in the case of hidden files - see below). + +- files whose Unix name begins with a dot will be presented as DOS hidden +files. The mangled name will be created as for other filenames, but with the +leading dot removed and "___" as its extension regardless of actual original +extension (that's three underscores). +.RE + +The two-digit hash value consists of upper case alphanumeric characters. + +This algorithm can cause name collisions only if files in a directory share +the same first five alphanumeric characters. The probability of such a clash +is 1/1300. + +The name mangling (if enabled) allows a file to be copied between Unix +directories from DOS while retaining the long Unix filename. Unix files can +be renamed to a new extension from DOS and will retain the same basename. +Mangled names do not change between sessions. + +.B Default: + mangled names = yes + +.B Example: + mangled names = no +.SS mangling char (S) +This controls what character is used as the "magic" character in name +mangling. The default is a ~ but this may interfere with some +software. Use this option to set it to whatever you prefer. + +.B Default: + mangling char = ~ + +.B Example: + mangling char = ^ + +.SS max log size (G) + +This option (an integer in kilobytes) specifies the max size the log +file should grow to. Samba periodically checks the size and if it is +exceeded it will rename the file, adding a .old extension. + +A size of 0 means no limit. + +.B Default: + max log size = 5000 + +.B Example: + max log size = 1000 + +.SS max xmit (G) + +This option controls the maximum packet size that will be negotiated +by Samba. The default is 65535, which is the maximum. In some cases +you may find you get better performance with a smaller value. A value +below 2048 is likely to cause problems. + +.B Default: + max xmit = 65535 + +.B Example: + max xmit = 8192 + +.SS mangled stack (G) +This parameter controls the number of mangled names that should be cached in +the Samba server. + +This stack is a list of recently mangled base names (extensions are only +maintained if they are longer than 3 characters or contains upper case +characters). + +The larger this value, the more likely it is that mangled names can be +successfully converted to correct long Unix names. However, large stack +sizes will slow most directory access. Smaller stacks save memory in the +server (each stack element costs 256 bytes). + +It is not possible to absolutely guarantee correct long file names, so +be prepared for some surprises! + +.B Default: + mangled stack = 50 + +.B Example: + mangled stack = 100 + +.SS map archive (S) +This controls whether the DOS archive attribute should be mapped to Unix +execute bits. The DOS archive bit is set when a file has been modified +since its last backup. One motivation for this option it to keep Samba/your +PC from making any file it touches from becoming executable under UNIX. +This can be quite annoying for shared source code, documents, etc... + +.B Default: + map archive = yes + +.B Example: + map archive = no + +.SS map hidden (S) +This controls whether DOS style hidden files should be mapped to Unix +execute bits. + +.B Default: + map hidden = no + +.B Example: + map hidden = yes +.SS map system (S) +This controls whether DOS style system files should be mapped to Unix +execute bits. + +.B Default: + map system = no + +.B Example: + map system = yes +.SS max connections (S) +This option allows the number of simultaneous connections to a +service to be limited. If "max connections" is greater than 0 then +connections will be refused if this number of connections to the +service are already open. A value of zero mean an unlimited number of +connections may be made. + +Record lock files are used to implement this feature. The lock files +will be stored in the directory specified by the "lock directory" option. + +.B Default: + max connections = 0 + +.B Example: + max connections = 10 +.SS only user (S) +This is a boolean option that controls whether connections with +usernames not in the user= list will be allowed. By default this +option is disabled so a client can supply a username to be used by +the server. + +Note that this also means Samba won't try to deduce usernames from the +service name. This can be annoying for the [homes] section. To get +around this you could use "user = %S" which means your "user" list +will be just the service name, which for home directories is the name +of the user. + +.B Default: + only user = False + +.B Example: + only user = True + +.SS message command (G) + +This specifies what command to run when the server receives a WinPopup +style message. + +This would normally be a command that would deliver the message +somehow. How this is to be done is up to your imagination. + +What I use is: + + message command = csh -c 'xedit %s;rm %s' & + +This delivers the message using xedit, then removes it +afterwards. NOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN +IMMEDIATELY. That's why I have the & on the end. If it doesn't return +immediately then your PCs may freeze when sending messages (they +should recover after 30secs, hopefully). + +All messages are delivered as the global guest user. The command takes +the standard substitutions, although %u won't work (%U may be better +in this case). + +Apart from the standard substitutions, some additional ones apply. In +particular: + +%s = the filename containing the message + +%t = the destination that the message was sent to (probably the server +name) + +%f = who the message is from + +You could make this command send mail, or whatever else takes your +fancy. Please let me know of any really interesting ideas you have. + +Here's a way of sending the messages as mail to root: + +message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s + +If you don't have a message command then the message won't be +delivered and Samba will tell the sender there was an +error. Unfortunately WfWg totally ignores the error code and carries +on regardless, saying that the message was delivered. + +If you want to silently delete it then try "message command = rm %s". + +For the really adventurous, try something like this: + +message command = csh -c 'csh < %s |& /usr/local/samba/smbclient \\ + -M %m; rm %s' & + +this would execute the command as a script on the server, then give +them the result in a WinPopup message. Note that this could cause a +loop if you send a message from the server using smbclient! You better +wrap the above in a script that checks for this :-) + +.B Default: + no message command + +.B Example: + message command = csh -c 'xedit %s;rm %s' & + +.SS min print space (S) + +This sets the minimum amount of free disk space that must be available +before a user will be able to spool a print job. It is specified in +kilobytes. The default is 0, which means no limit. + +.B Default: + min print space = 0 + +.B Example: + min print space = 2000 + +.SS null passwords (G) +Allow or disallow access to accounts that have null passwords. + +.B Default: + null passwords = no + +.B Example: + null passwords = yes + +.SS os level (G) +This integer value controls what level Samba advertises itself as for +browse elections. See BROWSING.txt for details. + +.SS packet size (G) +The maximum transmit packet size during a raw read. This option is no +longer implemented as of version 1.7.00, and is kept only so old +configuration files do not become invalid. + +.SS passwd chat (G) +This string coontrols the "chat" conversation that takes places +between smbd and the local password changing program to change the +users password. The string describes a sequence of response-receive +pairs that smbd uses to determine what to send to the passwd program +and what to expect back. If the expected output is not received then +the password is not changed. + +This chat sequence is often quite site specific, deppending on what +local methods are used for password control (such as NIS+ etc). + +The string can contain the macros %o and %n which are substituted for +the old and new passwords respectively. It can aso contain the +standard macros \\n \\r \\t and \\s to give line-feed, carriage-return, +tab and space. + +The string can also contain a * which matches any sequence of +characters. + +Double quotes can be used to collect strings with spaces in them into +a single string. + +If the send string in any part of the chat sequence is a fullstop "." +then no string is sent. Similarly, is the expect string is a fullstop +then no string is expected. + +.B Example: + passwd chat = "*Enter OLD password*" %o\\n "*Enter NEW password*" %n\\n \\ + "*Reenter NEW password*" %n\\n "*Password changed*" + +.B Default: + passwd chat = *old*password* %o\\n *new*password* %n\\n *new*password* %n\\n *changed* + +.SS passwd program (G) +The name of a program that can be used to set user passwords. + +This is only necessary if you have enabled remote password changing at +compile time. Any occurances of %u will be replaced with the user +name. + +Also note that many passwd programs insist in "reasonable" passwords, +such as a minimum length, or the inclusion of mixed case chars and +digits. This can pose a problem as some clients (such as Windows for +Workgroups) uppercase the password before sending it. + +.B Default: + passwd program = /bin/passwd + +.B Example: + passwd program = /sbin/passwd %u + +.SS password level (G) +Some client/server conbinations have difficulty with mixed-case passwords. +One offending client is Windows for Workgroups, which for some reason forces +passwords to upper case when using the LANMAN1 protocol, but leaves them alone +when using COREPLUS! + +This parameter defines the maximum number of characters that may be upper case +in passwords. + +For example, say the password given was "FRED". If +.B password level +is set to 1 (one), the following combinations would be tried if "FRED" failed: +"Fred", "fred", "fRed", "frEd", "freD". If +.B password level was set to 2 (two), the following combinations would also be +tried: "FRed", "FrEd", "FreD", "fREd", "fReD", "frED". And so on. + +The higher value this parameter is set to the more likely it is that a mixed +case password will be matched against a single case password. However, you +should be aware that use of this parameter reduces security and increases the +time taken to process a new connection. + +A value of zero will cause only two attempts to be made - the password as is +and the password in all-lower case. + +If you find the connections are taking too long with this option then +you probably have a slow crypt() routine. Samba now comes with a fast +"ufc crypt" that you can select in the Makefile. You should also make +sure the PASSWORD_LENGTH option is correct for your system in local.h +and includes.h. On most systems only the first 8 chars of a password +are significant so PASSWORD_LENGTH should be 8, but on some longer +passwords are significant. The inlcudes.h file tries to select the +right length for your system. + +.B Default: + password level = 0 + +.B Example: + password level = 4 + +.SS password server (G) + +By specifying the name of another SMB server (such as a WinNT box) +with this option, and using "security = server" you can get Samba to +do all it's username/password validation via a remote server. + +This options sets the name of the password server to use. It must be a +netbios name, so if the machines netbios name is different from it's +internet name then you may have to add it's netbios name to +/etc/hosts. + +The password server much be a machine capable of using the "LM1.2X002" +or the "LM NT 0.12" protocol, and it must be in user level security +mode. + +NOTE: Using a password server means your unix box (running Samba) is +only as secure as your password server. DO NOT CHOOSE A PASSWORD +SERVER THAT YOU DON'T COMPLETELY TRUST. + +Never point a Samba server at itself for password serving. This will +cause a loop and could lock up your Samba server! + +The name of the password server takes the standard substitutions, but +probably the only useful one is %m, which means the Samba server will +use the incoming client as the password server. If you use this then +you better trust your clients, and you better restrict them with hosts +allow! + +If you list several hosts in the "password server" option then smbd +will try each in turn till it finds one that responds. This is useful +in case your primary server goes down. + +.SS path (S) +A synonym for this parameter is 'directory'. + +This parameter specifies a directory to which the user of the service is to +be given access. In the case of printable services, this is where print data +will spool prior to being submitted to the host for printing. + +For a printable service offering guest access, the service should be readonly +and the path should be world-writable and have the sticky bit set. This is not +mandatory of course, but you probably won't get the results you expect if you +do otherwise. + +Any occurances of %u in the path will be replaced with the username +that the client is connecting as. Any occurances of %m will be +replaced by the name of the machine they are connecting from. These +replacements are very useful for setting up pseudo home directories +for users. + +Note that this path will be based on 'root dir' if one was specified. +.B Default: + none + +.B Example: + path = /home/fred+ + +.SS postexec (S) + +This option specifies a command to be run whenever the service is +disconnected. It takes the usual substitutions. The command may be run +as the root on some systems. + +An interesting example may be do unmount server resources: + +postexec = /etc/umount /cdrom + +See also preexec + +.B Default: + none (no command executed) + +.B Example: + postexec = echo \"%u disconnected from %S from %m (%I)\" >> /tmp/log + +.SS postscript (S) +This parameter forces a printer to interpret the print files as +postscript. This is done by adding a %! to the start of print output. + +This is most useful when you have lots of PCs that persist in putting +a control-D at the start of print jobs, which then confuses your +printer. + +.B Default: + postscript = False + +.B Example: + postscript = True + +.SS preexec (S) + +This option specifies a command to be run whenever the service is +connected to. It takes the usual substitutions. + +An interesting example is to send the users a welcome message every +time they log in. Maybe a message of the day? Here is an example: + +preexec = csh -c 'echo \"Welcome to %S!\" | \ + /usr/local/samba/smbclient -M %m -I %I' & + +Of course, this could get annoying after a while :-) + +See also postexec + +.B Default: + none (no command executed) + +.B Example: + preexec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log + +.SS preferred master (G) +This boolean parameter controls if Samba is a preferred master browser +for its workgroup. Setting this gives it a slight edge in elections +and also means it will automatically start an election when it starts +up. + +It is on by default. + +.SS preload +This is an alias for "auto services" + +.SS preserve case (S) + +This controls if new filenames are created with the case that the +client passes, or if they are forced to be the "default" case. + +.B Default: + preserve case = no + +See the section on "NAME MANGLING" for a fuller discussion. + +.SS print command (S) +After a print job has finished spooling to a service, this command will be +used via a system() call to process the spool file. Typically the command +specified will submit the spool file to the host's printing subsystem, but +there is no requirement that this be the case. The server will not remove the +spool file, so whatever command you specify should remove the spool file when +it has been processed, otherwise you will need to manually remove old spool +files. + +The print command is simply a text string. It will be used verbatim, +with two exceptions: All occurrences of "%s" will be replaced by the +appropriate spool file name, and all occurrences of "%p" will be +replaced by the appropriate printer name. The spool file name is +generated automatically by the server, the printer name is discussed +below. + +The full path name will be used for the filename if %s is not preceded +by a /. If you don't like this (it can stuff up some lpq output) then +use %f instead. Any occurances of %f get replaced by the spool +filename without the full path at the front. + +The print command MUST contain at least one occurrence of "%s" or %f - +the "%p" is optional. At the time a job is submitted, if no printer +name is supplied the "%p" will be silently removed from the printer +command. + +If specified in the [global] section, the print command given will be used +for any printable service that does not have its own print command specified. + +If there is neither a specified print command for a printable service nor a +global print command, spool files will be created but not processed and (most +importantly) not removed. + +Note that printing may fail on some unixes from the "nobody" +account. If this happens then create an alternative guest account that +can print and set the "guest account" in the [global] section. + +You can form quite complex print commands by realising that they are +just passed to a shell. For example the following will log a print +job, print the file, then remove it. Note that ; is the usual +separator for command in shell scripts. + +print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s + +You may have to vary this command considerably depending on how you +normally print files on your system. + +.B Default: + print command = lpr -r -P %p %s + +.B Example: + print command = /usr/local/samba/myprintscript %p %s +.SS print ok (S) +See +.B printable. +.SS printable (S) +A synonym for this parameter is 'print ok'. + +If this parameter is 'yes', then clients may open, write to and submit spool +files on the directory specified for the service. + +Note that a printable service will ALWAYS allow writing to the service path +(user privileges permitting) via the spooling of print data. The 'read only' +parameter controls only non-printing access to the resource. + +.B Default: + printable = no + +.B Example: + printable = yes + +.SS printing (G) +This parameters controls how printer status information is interpreted +on your system, and also affects the default values for the "print +command", "lpq command" and "lprm command". + +Currently three printing styles are supported. They are "printing = +bsd", "printing = sysv", "printing = hpux" and "printing = aix". + +To see what the defaults are for the other print commands when using +these three options use the "testparm" program. + + +.SS printcap name (G) +This parameter may be used to override the compiled-in default printcap +name used by the server (usually /etc/printcap). See the discussion of the +[printers] section above for reasons why you might want to do this. + +For those of you without a printcap (say on SysV) you can just create a +minimal file that looks like a printcap and set "printcap name =" in +[global] to point at it. + +A minimal printcap file would look something like this: + +print1|My Printer 1 +print2|My Printer 2 +print3|My Printer 3 +print4|My Printer 4 +print5|My Printer 5 + +where the | separates aliases of a printer. The fact that the second +alias has a space in it gives a hint to Samba that it's a comment. + +NOTE: Under AIX the default printcap name is "/etc/qconfig". Samba +will assume the file is in AIX "qconfig" format if the string +"/qconfig" appears in the printcap filename. + +.B Default: + printcap name = /etc/printcap + +.B Example: + printcap name = /etc/myprintcap +.SS printer (S) +A synonym for this parameter is 'printer name'. + +This parameter specifies the name of the printer to which print jobs spooled +through a printable service will be sent. + +If specified in the [global] section, the printer name given will be used +for any printable service that does not have its own printer name specified. + +.B Default: + none (but may be 'lp' on many systems) + +.B Example: + printer name = laserwriter +.SS printer name (S) +See +.B printer. +.SS protocol (G) +The value of the parameter (a string) is the highest protocol level that will +be supported by the server. + +Possible values are CORE, COREPLUS, LANMAN1, LANMAN2 and NT1. The relative +merits of each are discussed in the README file. + +.B Default: + protocol = NT1 + +.B Example: + protocol = LANMAN1 +.SS public (S) +A synonym for this parameter is 'guest ok'. + +If this parameter is 'yes' for a service, then no password is required +to connect to the service. Privileges will be those of the guest +account. + +See the section below on user/password validation for more information about +this option. + +.B Default: + public = no + +.B Example: + public = yes +.SS read list (S) +This is a list of users that are given read-only access to a +service. If the connecting user is in this list then they will +not be given write access, no matter what the "read only" option +is set to. The list can include group names using the @group syntax. + +See also the "write list" option + +.B Default: + read list = + +.B Example: + read list = mary, @students + +.SS read only (S) +See +.B writable +and +.B write ok. +Note that this is an inverted synonym for writable and write ok. +.SS read prediction (G) +This options enables or disables the read prediction code used to +speed up reads from the server. When enabled the server will try to +pre-read data from the last accessed file that was opened read-only +while waiting for packets. + +.SS Default: + read prediction = False + +.SS Example: + read prediction = True +.SS read raw (G) +This parameter controls whether or not the server will support raw reads when +transferring data to clients. + +If enabled, raw reads allow reads of 65535 bytes in one packet. This +typically provides a major performance benefit. + +However, some clients either negotiate the allowable block size incorrectly +or are incapable of supporting larger block sizes, and for these clients you +may need to disable raw reads. + +In general this parameter should be viewed as a system tuning tool and left +severely alone. See also +.B write raw. + +.B Default: + read raw = yes + +.B Example: + read raw = no +.SS read size (G) + +The option "read size" affects the overlap of disk reads/writes with +network reads/writes. If the amount of data being transferred in +several of the SMB commands (currently SMBwrite, SMBwriteX and +SMBreadbraw) is larger than this value then the server begins writing +the data before it has received the whole packet from the network, or +in the case of SMBreadbraw, it begins writing to the network before +all the data has been read from disk. + +This overlapping works best when the speeds of disk and network access +are similar, having very little effect when the speed of one is much +greater than the other. + +The default value is 2048, but very little experimentation has been +done yet to determine the optimal value, and it is likely that the best +value will vary greatly between systems anyway. A value over 65536 is +pointless and will cause you to allocate memory unnecessarily. + +.B Default: + read size = 2048 + +.B Example: + read size = 8192 + +.SS revalidate (S) + +This options controls whether Samba will allow a previously validated +username/password pair to be used to attach to a share. Thus if you +connect to \\\\server\\share1 then to \\\\server\\share2 it won't +automatically allow the client to request connection to the second +share as the same username as the first without a password. + +If "revalidate" is True then the client will be denied automatic +access as the same username. + +.B Default: + revalidate = False + +.B Example: + revalidate = True + +.SS root (G) +See +.B root directory. +.SS root dir (G) +See +.B root directory. +.SS root directory (G) +Synonyms for this parameter are 'root dir' and 'root'. + +The server will chroot() to this directory on startup. This is not +strictly necessary for secure operation. Even without it the server +will deny access to files not in one of the service entries. It may +also check for, and deny access to, soft links to other parts of the +filesystem, or attempts to use .. in file names to access other +directories (depending on the setting of the "wide links" parameter). + +Adding a "root dir" entry other than "/" adds an extra level of security, +but at a price. It absolutely ensures that no access is given to files not +in the sub-tree specified in the "root dir" option, *including* some files +needed for complete operation of the server. To maintain full operability +of the server you will need to mirror some system files into the "root dir" +tree. In particular you will need to mirror /etc/passwd (or a subset of it), +and any binaries or configuration files needed for printing (if required). +The set of files that must be mirrored is operating system dependent. + +.B Default: + root directory = / + +.B Example: + root directory = /homes/smb +.SS security (G) +This option does affects how clients respond to Samba. + +The option sets the "security mode bit" in replies to protocol negotiations +to turn share level security on or off. Clients decide based on this bit +whether (and how) to transfer user and password information to the server. + +The default is "security=SHARE", mainly because that was the only +option at one stage. + +The alternatives are "security = user" or "security = server". + +If your PCs use usernames that are the same as their usernames on the +unix machine then you will want to use "security = user". If you +mostly use usernames that don't exist on the unix box then use +"security = share". + +There is a bug in WfWg that may affect your decision. When in user +level security a WfWg client will totally ignore the password you type +in the "connect drive" dialog box. This makes it very difficult (if +not impossible) to connect to a Samba service as anyone except the +user that you are logged into WfWg as. + +If you use "security = server" then Samba will try to validate the +username/password by passing it to another SMB server, such as an NT +box. If this fails it will revert to "security = USER". + +See the "password server" option for more details. + +.B Default: + security = SHARE + +.B Example: + security = USER +.SS server string (G) +This controls what string will show up in the printer comment box in +print manager and next to the IPC connection in "net view". It can be +any string that you wish to show to your users. + +Note that it DOES NOT affect the string that appears in browse +lists. That is controlled by a nmbd command line option instead. + +A %v will be replaced with the Samba version number. + +A %h will be replaced with the hostname. + +.B Default: + server string = Samba %v + +.B Example: + server string = University of GNUs Samba Server + +.SS smbrun (G) +This sets the full path to the smbrun binary. This defaults to the +value in the Makefile. + +You must get this path right for many services to work correctly. + +.B Default: taken from Makefile + +.B Example: + smbrun = /usr/local/samba/bin/smbrun + +.SS short preserve case (S) + +This controls if new short filenames are created with the case that +the client passes, or if they are forced to be the "default" case. + +.B Default: + short preserve case = no + +See the section on "NAME MANGLING" for a fuller discussion. + +.SS root preexec (S) + +This is the same as preexec except that the command is run as +root. This is useful for mounting filesystems (such as cdroms) before +a connection is finalised. + +.SS root postexec (S) + +This is the same as postexec except that the command is run as +root. This is useful for unmounting filesystems (such as cdroms) after +a connection is closed. + +.SS set directory (S) +If 'set directory = no', then users of the service may not use the setdir +command to change directory. + +The setdir comand is only implemented in the Digital Pathworks client. See the +Pathworks documentation for details. +.B Default: + set directory = no + +.B Example: + set directory = yes + +.SS share modes (S) + +This enables or disables the honouring of the "share modes" during a +file open. These modes are used by clients to gain exclusive read or +write access to a file. + +These open modes are not directly supported by unix, so they are +simulated using lock files in the "lock directory". The "lock +directory" specified in smb.conf must be readable by all users. + +The share modes that are enabled by this option are DENY_DOS, +DENY_ALL, DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB. + +Enabling this option gives full share compatability but may cost a bit +of processing time on the unix server. They are enabled by default. + +.B Default: + share modes = yes + +.B Example: + share modes = no + +.SS socket options (G) +This option (which can also be invoked with the -O command line +option) allows you to set socket options to be used when talking with +the client. + +Socket options are controls on the networking layer of the operating +systems which allow the connection to be tuned. + +This option will typically be used to tune your Samba server for +optimal performance for your local network. There is no way that Samba +can know what the optimal parameters are for your net, so you must +experiment and choose them yourself. I strongly suggest you read the +appropriate documentation for your operating system first (perhaps +"man setsockopt" will help). + +You may find that on some systems Samba will say "Unknown socket +option" when you supply an option. This means you either mis-typed it +or you need to add an include file to includes.h for your OS. If the +latter is the case please send the patch to me +(samba-bugs@anu.edu.au). + +Any of the supported socket options may be combined in any way you +like, as long as your OS allows it. + +This is the list of socket options currently settable using this +option: + + SO_KEEPALIVE + + SO_REUSEADDR + + SO_BROADCAST + + TCP_NODELAY + + IPTOS_LOWDELAY + + IPTOS_THROUGHPUT + + SO_SNDBUF * + + SO_RCVBUF * + + SO_SNDLOWAT * + + SO_RCVLOWAT * + +Those marked with a * take an integer argument. The others can +optionally take a 1 or 0 argument to enable or disable the option, by +default they will be enabled if you don't specify 1 or 0. + +To specify an argument use the syntax SOME_OPTION=VALUE for example +SO_SNDBUF=8192. Note that you must not have any spaces before or after +the = sign. + +If you are on a local network then a sensible option might be + +socket options = IPTOS_LOWDELAY + +If you have an almost unloaded local network and you don't mind a lot +of extra CPU usage in the server then you could try + +socket options = IPTOS_LOWDELAY TCP_NODELAY + +If you are on a wide area network then perhaps try setting +IPTOS_THROUGHPUT. + +Note that several of the options may cause your Samba server to fail +completely. Use these options with caution! + +.B Default: + no socket options + +.B Example: + socket options = IPTOS_LOWDELAY + + + + +.SS status (G) +This enables or disables logging of connections to a status file that +smbstatus can read. + +With this disabled smbstatus won't be able to tell you what +connections are active. + +.B Default: + status = yes + +.B Example: + status = no + +.SS strip dot (G) +This is a boolean that controls whether to strup trailing dots off +filenames. This helps with some CDROMs that have filenames ending in a +single dot. + +NOTE: This option is now obsolete, and may be removed in future. You +should use the "mangled map" option instead as it is much more +general. + +.SS strict locking (S) +This is a boolean that controls the handling of file locking in the +server. When this is set to yes the server will check every read and +write access for file locks, and deny access if locks exist. This can +be slow on some systems. + +When strict locking is "no" the server does file lock checks only when +the client explicitly asks for them. + +Well behaved clients always ask for lock checks when it is important, +so in the vast majority of cases "strict locking = no" is preferable. + +.B Default: + strict locking = no + +.B Example: + strict locking = yes + +.SS sync always (S) + +This is a boolean parameter that controls whether writes will always +be written to stable storage before the write call returns. If this is +false then the server will be guided by the clients request in each +write call (clients can set a bit indicating that a particular write +should be synchronous). If this is true then every write will be +followed by a fsync() call to ensure the data is written to disk. + +.B Default: + sync always = no + +.B Example: + sync always = yes + +.SS time offset (G) +This parameter is a setting in minutes to add to the normal GMT to +local time conversion. This is useful if you are serving a lot of PCs +that have incorrect daylight saving time handling. + +.B Default: + time offset = 0 + +.B Example: + time offset = 60 + +.SS user (S) +See +.B username. +.SS username (S) +A synonym for this parameter is 'user'. + +Multiple users may be specified in a comma-delimited list, in which case the +supplied password will be tested against each username in turn (left to right). + +The username= line is needed only when the PC is unable to supply it's own +username. This is the case for the coreplus protocol or where your +users have different WfWg usernames to unix usernames. In both these +cases you may also be better using the \\\\server\\share%user syntax +instead. + +The username= line is not a great solution in many cases as it means Samba +will try to validate the supplied password against each of the +usernames in the username= line in turn. This is slow and a bad idea for +lots of users in case of duplicate passwords. You may get timeouts or +security breaches using this parameter unwisely. + +Samba relies on the underlying unix security. This parameter does not +restrict who can login, it just offers hints to the Samba server as to +what usernames might correspond to the supplied password. Users can +login as whoever they please and they will be able to do no more +damage than if they started a telnet session. The daemon runs as the +user that they log in as, so they cannot do anything that user cannot +do. + +To restrict a service to a particular set of users you can use the +"valid users=" line. + +If any of the usernames begin with a @ then the name will be looked up +in the groups file and will expand to a list of all users in the group +of that name. Note that searching though a groups file can take quite +some time, and some clients may time out during the search. + +See the section below on username/password validation for more information +on how this parameter determines access to the services. + +.B Default: + The guest account if a guest service, else the name of the service. + +.B Examples: + username = fred + username = fred, mary, jack, jane, @users, @pcgroup + +.SS username map (G) + +This option allows you to to specify a file containing a mapping of +usernames from the clients to the server. This can be used for several +purposes. The most common is to map usernames that users use on dos or +windows machines to those that the unix box uses. The other is to map +multiple users to a single username so that they can more easily share +files. + +The map file is parsed line by line. Each line should contain a single +unix username on the left then a '=' followed by a list of usernames +on the right. The list of usernames on the right may contain names of +the form @group in which case they will match any unix username in +that group. The special client name '*' is a wildcard and matches any +name. + +The file is processed on each line by taking the supplied username and +comparing it with each username on the right hand side of the '=' +signs. If the supplied name matrches any of the names on the right +hand side then it is replaced with the name on the left. Processing +then continues with the next line. + +If any line begins with a '#' or a ';' then it is ignored + +For example to map from he name "admin" or "administrator" to the unix +name "root" you would use + + root = admin administrator + +Or to map anyone in the unix group "system" to the unix name "sys" you +would use + + sys = @system + +You can have as many mappings as you like in a username map file. + +Note that the remapping is applied to all occurances of +usernames. Thus if you connect to "\\\\server\\fred" and "fred" is +remapped to "mary" then you will actually be connecting to +"\\\\server\\mary" and will need to supply a password suitable for +"mary" not "fred". The only exception to this is the username passwed +to the "password server" (if you have one). The password server will +receive whatever username the client supplies without modification. + +Also note that no reverse mapping is done. The main effect this has is +with printing. Users who have been mapped may have trouble deleting +print jobs as PrintManager under WfWg will think they don't own the +print job. + +.B Default + no username map + +.B Example + username map = /usr/local/samba/lib/users.map + +.SS valid chars (S) + +The option allows you to specify additional characters that should be +considered valid by the server in filenames. This is particularly +useful for national character sets, such as adding u-umlaut or a-ring. + +The option takes a list of characters in either integer or character +form with spaces between them. If you give two characters with a colon +between them then it will be taken as an lowercase:uppercase pair. + +If you have an editor capable of entering the characters into the +config file then it is probably easiest to use this method. Otherwise +you can specify the characters in octal, decimal or hexidecimal form +using the usual C notation. + +For example to add the single character 'Z' to the charset (which is a +pointless thing to do as it's already there) you could do one of the +following + +valid chars = Z +valid chars = z:Z +valid chars = 0132:0172 + +The last two examples above actually add two characters, and alters +the uppercase and lowercase mappings appropriately. + +.B Default + Samba defaults to using a reasonable set of valid characters + for english systems + +.B Example + valid chars = 0345:0305 0366:0326 0344:0304 + +The above example allows filenames to have the swedish characters in +them. + +.SS valid users (S) +This is a list of users that should be allowed to login to this +service. A name starting with @ is interpreted as a unix group. + +If this is empty (the default) then any user can login. If a username +is in both this list and the "invalid users" list then access is +denied for that user. + +The current servicename is substituted for %S. This is useful in the +[homes] section. + +See also "invalid users" + +.B Default + No valid users list. (anyone can login) + +.B Example + valid users = greg, @pcusers + +.SS volume (S) +This allows you to override the volume label returned for a +share. Useful for CDROMs whos installation programs insist on a +particular volume label. + +The default is the name of the share + +.SS wide links (S) +This parameter controls whether or not links in the Unix file system may be +followed by the server. Links that point to areas within the directory tree +exported by the server are always allowed; this parameter controls access +only to areas that are outside the directory tree being exported. + +.B Default: + wide links = yes + +.B Example: + wide links = no + +.SS workgroup (G) + +This controls what workgroup your server will appear to be in when +queried by clients. This can be different to the workgroup specified +in the nmbd configuration, but it is probably best if you set them to +the same value. + +.B Default: + set in the Makefile + +.B Example: + workgroup = MYGROUP + +.SS write ok (S) +See +.B writable +and +.B read only. +.SS writable (S) +A synonym for this parameter is 'write ok'. An inverted synonym is 'read only'. + +If this parameter is 'no', then users of a service may not create or modify +files in the service's directory. + +Note that a printable service ('printable = yes') will ALWAYS allow +writing to the directory (user privileges permitting), but only via +spooling operations. + +.B Default: + writable = no + +.B Examples: + read only = no + writable = yes + write ok = yes +.SS write list (S) +This is a list of users that are given read-write access to a +service. If the connecting user is in this list then they will be +given write access, no matter what the "read only" option is set +to. The list can include group names using the @group syntax. + +Note that if a user is in both the read list and the write list then +they will be given write access. + +See also the "read list" option + +.B Default: + write list = + +.B Example: + write list = admin, root, @staff + +.SS write raw (G) +This parameter controls whether or not the server will support raw writes when +transferring data from clients. + +.B Default: + write raw = yes + +.B Example: + write raw = no +.SH NOTE ABOUT USERNAME/PASSWORD VALIDATION +There are a number of ways in which a user can connect to a +service. The server follows the following steps in determining if it +will allow a connection to a specified service. If all the steps fail +then the connection request is rejected. If one of the steps pass then +the following steps are not checked. + +If the service is marked "guest only = yes" then steps 1 to 5 are skipped + +Step 1: If the client has passed a username/password pair and that +username/password pair is validated by the unix systems password +programs then the connection is made as that username. Note that this +includes the \\\\server\\service%username method of passing a username. + +Step 2: If the client has previously registered a username with the +system and now supplies a correct password for that username then the +connection is allowed. + +Step 3: The clients netbios name and any previously used user names +are checked against the supplied password, if they match then the +connection is allowed as the corresponding user. + +Step 4: If the client has previously validated a username/password +pair with the server and the client has passed the validation token +then that username is used. This step is skipped if "revalidate = yes" +for this service. + +Step 5: If a "user = " field is given in the smb.conf file for the +service and the client has supplied a password, and that password +matches (according to the unix systems password checking) with one of +the usernames from the user= field then the connection is made as the +username in the "user=" line. If one of the username in the user= list +begins with a @ then that name expands to a list of names in the group +of the same name. + +Step 6: If the service is a guest service then a connection is made as +the username given in the "guest account =" for the service, +irrespective of the supplied password. + + +.SH WARNINGS +Although the configuration file permits service names to contain spaces, +your client software may not. Spaces will be ignored in comparisons anyway, +so it shouldn't be a problem - but be aware of the possibility. + +On a similar note, many clients - especially DOS clients - limit service +names to eight characters. Smbd has no such limitation, but attempts +to connect from such clients will fail if they truncate the service names. +For this reason you should probably keep your service names down to eight +characters in length. + +Use of the [homes] and [printers] special sections make life for an +administrator easy, but the various combinations of default attributes can be +tricky. Take extreme care when designing these sections. In particular, +ensure that the permissions on spool directories are correct. +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the server has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. + +Prior to version 1.5.21 of the Samba suite, the configuration file was +radically different (more primitive). If you are using a version earlier than +1.8.05, it is STRONGLY recommended that you upgrade. +.SH OPTIONS +Not applicable. + +.SH FILES +Not applicable. + +.SH ENVIRONMENT VARIABLES +Not applicable. + +.SH SEE ALSO +.B smbd(8), +.B smbclient(1), +.B nmbd(8), +.B testparm(1), +.B testprns(1), +.B lpq(1), +.B hosts_access(5) +.SH DIAGNOSTICS +[This section under construction] + +Most diagnostics issued by the server are logged in a specified log file. The +log file name is specified at compile time, but may be overridden on the +smbd (see smbd(8)) command line. + +The number and nature of diagnostics available depends on the debug level used +by the server. If you have problems, set the debug level to 3 and peruse the +log files. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. + +.SH BUGS +None known. + +Please send bug reports, comments and so on to: + +.RS 3 +.B samba-bugs@anu.edu.au (Andrew Tridgell) + +.RS 3 +or to the mailing list +.RE + +.B samba@listproc.anu.edu.au + +.RE +You may also like to subscribe to the announcement channel + +.RS 3 +samba-announce@listproc.anu.edu.au +.RE + +To subscribe to these lists send a message to +listproc@listproc.anu.edu.au with a body of "subscribe samba Your +Name" or "subscribe samba-announce Your Name". + +Errors or suggestions for improvements to the Samba man pages should be +mailed to: + +.RS 3 +.B samba-bugs@anu.edu.au (Andrew Tridgell) +.RE + diff --git a/docs/manpages/smbclient.1 b/docs/manpages/smbclient.1 new file mode 100644 index 0000000000..5590e01296 --- /dev/null +++ b/docs/manpages/smbclient.1 @@ -0,0 +1,1133 @@ +.TH SMBCLIENT 1 17/1/1995 smbclient smbclient +.SH NAME +smbclient \- ftp-like Lan Manager client program +.SH SYNOPSIS +.B smbclient +.B servicename +[ +.B password +] [ +.B -A +] [ +.B -E +] [ +.B -L +.I host +] [ +.B -M +.I host +] [ +.B -I +.I IP number +] [ +.B -N +] [ +.B -P +] [ +.B -U +.I username +] [ +.B -d +.I debuglevel +] [ +.B -l +.I log basename +] [ +.B -n +.I netbios name +] [ +.B -O +.I socket options +] [ +.B -p +.I port number +.B -T +.I tar options +.B -D +.I initial directory +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B smbclient +is a client that can 'talk' to a Lan Manager server. It offers +an interface similar to that of the +.B ftp +program (see +.B ftp(1)). Operations include things like getting files from the +server to the local machine, putting files from the local machine to +the server, retrieving directory information from the server and so on. + +.SH OPTIONS +.B servicename +.RS 3 +.B servicename +is the name of the service you want to use on the server. A service +name takes the form +.B "\\\\\\\\server\\\\service" +where +.B server +is the netbios name of the Lan Manager server offering the desired service and +.B service +is the name of the service offered. Thus to connect to the service "printer" +on the Lan Manager server "lanman", you would use the servicename + +.RS 10 +.B "\\\\\\\\lanman\\\\printer" +.RE + +Note that the server name required is NOT necessarily the host name of the +server! The name required is a Lan Manager server name, which may or may not +be the same as the hostname of the machine running the server. +.RE + +.B password +.RS 3 +.B +password +is the password required to access the specified service on the +specified server. If supplied, the +.B -N +option (suppress password prompt) is assumed. + +There is no default password. If no password is supplied on the command line +(either here or using the +.B -U +option (see below)) and +.B -N +is not specified, the client will prompt for a password, even if the desired +service does not require one. (If prompted for a password and none is +required, simply press ENTER to provide a null password.) + +Note: Some servers (including OS/2 and Windows for Workgroups) insist +on an uppercase password. Lowercase or mixed case passwords may be +rejected by these servers. + +Be cautious about including passwords in scripts. +.RE + +.B -A + +.RS 3 +This parameter, if specified, causes the maximum debug level to be selected. +Be warned that this generates prodigious amounts of debug data. There is also +a security issue involved, as at the maximum debug level cleartext passwords +may be written to some log files. +.RE + +.B -L + +.RS 3 +This option allows you to look at what services are available on a +server. You use it as "smbclient -L host" and a list should appear. +The -I option may be useful if your netbios names don't match your +tcp/ip host names or if you are trying to reach a host on another +network. For example: + +smbclient -L ftp -I ftp.microsoft.com + +will list the shares available on microsofts public server. +.RE + +.B -M + +.RS 3 +This options allows you to send messages, using the "WinPopup" +protocol, to another computer. Once a connection is established you +then type your message, pressing ^D (control-D) to end. + +If the receiving computer is running WinPopup the user will receive +the message and probably a beep. If they are not running WinPopup the +message will be lost, and no error message will occur. + +The message is also automatically truncated if the message is over +1600 bytes, as this is the limit of the protocol. + +One useful trick is to cat the message through smbclient. For example: + +cat mymessage.txt | smbclient -M FRED + +will send the message in the file "mymessage.txt" to the machine FRED. + +You may also find the -U and -I options useful, as they allow you to +control the FROM and TO parts of the message. + +Samba currently has no way of receiving WinPopup messages. + +Note: Copy WinPopup into the startup group on your WfWg PCs if you +want them to always be able to receive messages. +.RE + +.B -E + +.RS 3 +This parameter, if specified, causes the client to write messages to the +standard error stream (stderr) rather than to the standard output stream. + +By default, the client writes messages to standard output - typically the +user's tty. +.RE + +.B -I +.I IP number + +.RS 3 +.I IP number +represents the IP number of the server to connect to. It should +be specified in standard "a.b.c.d" notation. + +Normally the client will attempt to locate the specified Lan Manager server +by looking it up - that is, broadcasting a request for the given server to +identify itself. Using this parameter will force the client to assume that +the server is on the machine with the specified IP number. + +There is no default for this parameter. If not supplied, it will be determined +automatically by the client as described above. +.RE + +.B -N + +.RS 3 +If specified, this parameter suppresses the normal password prompt from the +client to the user. This is useful when accessing a service that does not +require a password. + +Unless a password is specified on the command line or this parameter is +specified, the client will request a password. +.RE + +.B -O +.I socket options +.RS 3 + +See the socket options section of smb.conf(5) for details + +.RE +.B -P + +.RS 3 +If specified, the service requested will be connected to as a printer service +rather than as a normal filespace service. Operations such as put and get +will not be applicable for such a connection. + +By default, services will be connected to as NON-printer services. +.RE + +.B -U +.I username + +.RS 3 +.I username +is the user name that will be used by the client to make a connection, +assuming your server is running a protocol that allows for usernames. + +Some servers are fussy about the case of this name, and some insist +that it must be a valid netbios name. + +If no +.I username +is supplied, it will default to an uppercase version of the +environment variable +.B USER +or +.B LOGNAME +in that order. +If no +.I username +is supplied and neither environment variable exists the user name will +be empty. + +If the service you are connecting to requires a password, it can be supplied +using the +.B -U +option, by appending a percent symbol ("%") then the password to +.I username. +For example, to attach to a service as user "fred" with password "secret", you +would specify +.B -U +.I fred%secret +on the command line. Note that there are no spaces around the percent symbol. + +If you specify the password as part of +.I username +then the +.B -N +option (suppress password prompt) is assumed. + +If you specify the password as a parameter AND as part of +.I username +then the password as part of +.I username +will take precedence. Putting nothing before or nothing after the percent +symbol will cause an empty username or an empty password to be used, +respectively. + +Note: Some servers (including OS/2 and Windows for Workgroups) insist +on an uppercase password. Lowercase or mixed case passwords may be +rejected by these servers. + +Be cautious about including passwords in scripts. +.RE + +.B -d +.I debuglevel +.RS 3 + +debuglevel is an integer from 0 to 5. + +The default value if this parameter is not specified is zero. + +The higher this value, the more detail will be logged to the log files about +the activities of the client. At level 0, only critical errors and serious +warnings will be logged. Level 1 is a reasonable level for day to day running +- it generates a small amount of information about operations carried out. + +Levels above 1 will generate considerable amounts of log data, and should +only be used when investigating a problem. Levels above 3 are designed for +use only by developers and generate HUGE amounts of log data, most of which +is extremely cryptic. +.RE + +.B -l +.I log basename + +.RS 3 +If specified, +.I log basename +specifies a base filename into which operational data from the running client +will be logged. + +The default base name is specified at compile time. + +The base name is used to generate actual log file names. For example, if the +name specified was "log", the following files would be used for log data: + +.RS 3 +log.client.debug (containing debugging information) + +log.client.in (containing inbound transaction data) + +log.client.out (containing outbound transaction data) +.RE + +The log files generated are never removed by the client. +.RE +.RE + +.B -n +.I netbios name + +.RS 3 +By default, the client will use the local machine's hostname (in +uppercase) as its netbios name. This parameter allows you to override +the host name and use whatever netbios name you wish. +.RE + +.B -p +.I port number +.RS 3 + +port number is a positive integer value. + +The default value if this parameter is not specified is 139. + +This number is the port number that will be used when making connections to +the server. The standard (well-known) port number for the server is 139, +hence the default. + +This parameter is not normally specified. + +.B -T +.I tar options +.RS3 + +where tar options are one or more of c,x,I,X,b,g,N or a; used as: +.LP +smbclient +.B "\\\\\\\\server\\\\share" +\-TcxIXbgNa +[ +.IR blocksize +] +[ +.IR newer-file +] +.IR tarfile +[ +.IR filenames.... +] + +.RS3 +.B c +Create a tar file on UNIX. Must be followed by the name of a tar file, +tape device or "-" for standard output. (May be useful to set debugging +low (-d0)) to avoid corrupting your tar file if using "-"). Mutually +exclusive with the x flag. + +.B x +Extract (restore) a local tar file back to a share. Unless the -D +option is given, the tar files will be restored from the top level of +the share. Must be followed by the name of the tar file, device or "-" +for standard input. Mutually exclusive with the c flag. + +.B I +Include files and directories. Is the default behaviour when +.IR filenames +are specified above. Causes tar files to be included in an extract or create +(and therefore everything else to be excluded). See example below. +Filename globbing does not work for included files for extractions (yet). + +.B X +Exclude files and directories. Causes tar files to be excluded from +an extract or create. See example below. +Filename globbing does not work for excluded files (yet). + +.B b +Blocksize. Must be followed by a valid (greater than zero) blocksize. +Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte) +blocks. + +.B g +Incremental. Only back up files that have the archive bit set. Useful +only with the c flag. + +.B N +Newer than. Must be followed by the name of a file whose date is +compared against files found on the share during a create. Only files +newer than the file specified are backed up to the tar file. Useful +only with the c flag. + +.B a +Set archive bit. Causes the archive bit to be reset when a file is backed +up. Useful with the g (and c) flags. +.LP + +.B Examples + +smbclient \\\\mypc\\myshare "" -N -Tx backup.tar + +Restore from tar file backup.tar into myshare on mypc (no password on share). + +smbclient \\\\mypc\\myshare "" -N -TXx backup.tar users/docs + +Restore everything except users/docs + +smbclient \\\\mypc\\myshare "" -N -Tc backup.tar users/docs + +Create a tar file of the files beneath users/docs. + +.RE + +.B -D +.I initial directory + +.RS3 + +Change to initial directory before starting. Probably only of any use +with the tar (\-T) option. + + +.RE + +.SH OPERATIONS +Once the client is running, the user is presented with a prompt, "smb: \\>". +The backslash ("\\") indicates the current working directory on the server, +and will change if the current working directory is changed. + +The prompt indicates that the client is ready and waiting to carry out a user +command. Each command is a single word, optionally followed by parameters +specific to that command. Command and parameters are space-delimited unless +these notes specifically state otherwise. All commands are case-insensitive. +Parameters to commands may or may not be case sensitive, depending on the +command. + +You can specify file names which have spaces in them by quoting the +name with double quotes, for example "a long file name". + +Parameters shown in square brackets (eg., "[parameter]") are optional. If not +given, the command will use suitable defaults. Parameters shown in angle +brackets (eg., "") are required. + +Note that all commands operating on the server are actually performed by +issuing a request to the server. Thus the behaviour may vary from server to +server, depending on how the server was implemented. + +The commands available are given here in alphabetical order. + +.B ? +.RS 3 +.B Parameters: +.RS 3 +.I [command] + +.RE +.B Description: +.RS 3 +If +.I command +is specified, the +.B ? +command will display a brief informative message about the specified command. + +If no command is specified, a list of available commands will be displayed. +.RE +.RE + +.B ! +.RS 3 +.B Parameters: +.RS 3 +.I [shell command] + +.RE +.B Description: +.RS 3 +If +.I shell command +is specified, the +.B ! +command will execute a shell locally and run the specified shell command. If +no command is specified, a shell will be run. +.RE +.RE + +.B cd +.RS 3 +.B Parameters: +.RS 3 +.I [directory name] + +.RE +.B Description: +.RS 3 +If +.I directory name +is specified, the current working directory +.B on the server +will be changed to the directory specified. This operation will fail if for +any reason the specified directory is inaccessible. + +If no directory name is specified, the current working directory +.B on the server +will be reported. +.RE +.RE + +.B del +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +The client will request that the server attempt to delete all files matching +.I mask +from the current working directory +.B on the server. +.RE +.RE + +.B dir +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +A list of the files matching +.I mask +in the current working directory +.B on the server +will be retrieved from the server and displayed. +.RE +.RE + +.B exit +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Terminate the connection with the server and exit from the program. +.RE +.RE + +.B get +.RS 3 +.B Parameters: +.RS 3 +.I [local file name] + +.RE +.B Description: +.RS 3 +Copy the file called +.I remote file name +from the server to the machine running the client. If specified, name the +local copy +.I local file name. +Note that all transfers in smbclient are binary. See also the +.B lowercase +command. +.RE +.RE + +.B help +.RS 3 +.B Parameters: +.RS 3 +.I [command] + +.RE +.B Description: +.RS 3 +See the +.B ? +command above. +.RE +.RE + +.B lcd +.RS 3 +.B Parameters: +.RS 3 +.I [directory name] + +.RE +.B Description: +.RS 3 +If +.I directory name +is specified, the current working directory +.B on the local machine +will be changed to the directory specified. This operation will fail if for +any reason the specified directory is inaccessible. + +If no directory name is specified, the name of the current working directory +.B on the local machine +will be reported. +.RE +.RE + +.B lowercase +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle lowercasing of filenames for the +.B get +and +.B mget +commands. + +When lowercasing is toggled ON, local filenames are converted to lowercase +when using the +.B get +and +.B mget +commands. This is often useful when copying (say) MSDOS files from a server, +because lowercase filenames are the norm on Unix systems. +.RE +.RE + +.B ls +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +See the +.B dir +command above. +.RE +.RE + +.B mask +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +This command allows the user to set up a mask which will be used during +recursive operation of the +.B mget +and +.B mput +commands. + +The masks specified to the +.B mget +and +.B mput +commands act as filters for directories +rather than files when recursion is toggled ON. + +The mask specified with the +.B mask +command is necessary to filter files within those directories. For example, +if the mask specified in an +.B mget +command is "source*" +.I and +the mask specified with the +.B mask +command is "*.c" +.I and +recursion is toggled ON, the +.B mget +command will retrieve all files matching "*.c" in all directories below +and including all directories matching "source*" in the current working +directory. + +Note that the value for +.I mask +defaults to blank (equivalent to "*") and remains so until the +.B mask +command is used to change it. It retains the most recently specified value +indefinitely. To avoid unexpected results it would be wise to change the +value of +.I mask +back to "*" after using the +.B mget +or +.B mput +commands. +.RE +.RE + +.B md +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +See the +.B mkdir +command. +.RE +.RE + +.B mget +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Copy all files matching +.I mask +from the server to the machine running the client. + +Note that +.I mask +is interpreted differently during recursive operation and non-recursive +operation - refer to the +.B recurse +and +.B mask +commands for more information. Note that all transfers in smbclient are +binary. See also the +.B lowercase +command. +.RE +.RE + +.B mkdir +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Create a new directory +.B on the server +(user access privileges permitting) with the specified name. +.RE +.RE + +.B mput +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Copy all files matching +.I mask +in the current working directory +.B on the local machine +to the current working directory on the server. + +Note that +.I mask +is interpreted differently during recursive operation and non-recursive +operation - refer to the +.B recurse +and +.B mask +commands for more information. Note that all transfers in smbclient are +binary. +.RE +.RE + +.B print +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Print the specified file +.B from the local machine +through a printable service on the server. + +See also the +.B printmode +command. +.RE +.RE + +.B printmode +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Set the print mode to suit either binary data (such as graphical information) +or text. Subsequent +.B print +commands will use the currently set print mode. +.RE +.RE + +.B prompt +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle prompting for filenames during operation of the +.B mget +and +.B mput +commands. + +When toggled ON, the user will be prompted to confirm the transfer of each +file during these commands. When toggled OFF, all specified files will be +transferred without prompting. +.RE +.RE + +.B put +.RS 3 +.B Parameters: +.RS 3 +.I [remote file name] + +.RE +.B Description: +.RS 3 +Copy the file called +.I local file name +from the machine running the client to the server. If specified, name the +remote copy +.I remote file name. +Note that all transfers in smbclient are binary. See also the +.B lowercase +command. +.RE +.RE + +.B queue +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Displays the print queue, showing the job id, name, size and current status. +.RE +.RE + +.B quit +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +See the +.B exit +command. +.RE +.RE + +.B rd +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +See the +.B rmdir +command. +.RE +.RE + +.B recurse +.RS 3 +.B Parameters: +.RS 3 +None. + +.RE +.B Description: +.RS 3 +Toggle directory recursion for the commands +.B mget +and +.B mput +. + +When toggled ON, these commands will process all directories in the source +directory (ie., the directory they are copying +.I from +) and will recurse into any that match the mask specified to the command. Only +files that match the mask specified using the +.B mask +command will be retrieved. See also the +.mask +command. + +When recursion is toggled OFF, only files from the current working +directory on the source machine that match the mask specified to the +.B mget +or +.B mput +commands will be copied, and any mask specified using the +.B mask +command will be ignored. +.RE +.RE + +.B rm +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Remove all files matching +.I mask +from the current working directory +.B on the server. +.RE +.RE + +.B rmdir +.RS 3 +.B Parameters: +.RS 3 +.I + +.RE +.B Description: +.RS 3 +Remove the specified directory (user access privileges permitting) +.B from the server. +.RE +.RE + +.B tar +.RS 3 +.B Parameters: +.RS 3 +.I [IXbgNa] + +.RE +.B Description: +.RS 3 +Performs a tar operation - see -T command line option above. Behaviour +may be affected by the +.B tarmode +command (see below). Using the g (incremental) and N (newer) will affect +tarmode settings. Note that using the "-" option with tar x may not +work - use the command line option instead. +.RE +.RE + +.B blocksize +.RS 3 +.B Parameters +.RS 3 +.I + +.RE +.B Description +.RS 3 +Blocksize. Must be followed by a valid (greater than zero) blocksize. +Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte) +blocks. +.RE +.RE + +.B tarmode +.RS 3 +.B Parameters +.RS 3 +.I + +.RE +.B Description +.RS 3 +Changes tar's behaviour with regard to archive bits. In full mode, +tar will back up everything regardless of the archive bit setting (this +is the default mode). In incremental mode, tar will only back up files +with the archive bit set. In reset mode, tar will reset the archive bit +on all files it backs up (implies read/write share). +.RE +.RE + +.B setmode +.RS 3 +.B Parameters +.RS 3 +.I + +.RE +.B Description +.RS 3 +A version of the DOS attrib command to set file permissions. For example, + +setmode myfile +r + +would make myfile read only. +.RE +.RE + +.SH NOTES +Some servers are fussy about the case of supplied usernames, passwords, share +names (aka service names) and machine names. If you fail to connect try +giving all parameters in uppercase. + +It is often necessary to use the +.B -n +option when connecting to some types +of servers. For example OS/2 LanManager insists on a valid netbios name +being used, so you need to supply a valid name that would be known to +the server. + +.B smbclient +supports long file names where the server supports the LANMAN2 +protocol. + +.SH FILES +Not applicable. + +.SH ENVIRONMENT VARIABLES +.B USER +.RS 3 +The variable USER may contain the username of the person using the client. +This information is used only if the protocol level is high enough to support +session-level passwords. +.RE + +.SH INSTALLATION +The location of the client program is a matter for individual system +administrators. The following are thus suggestions only. + +It is recommended that the client software be installed under the /usr/local +hierarchy, in a directory readable by all, writeable only by root. The client +program itself should be executable by all. The client should NOT be setuid +or setgid! + +The client log files should be put in a directory readable and writable only +by the user. + +To test the client, you will need to know the name of a running Lan manager +server. It is possible to run the smbd (see +.B smbd(8)) as an ordinary user - running that server as a daemon on a +user-accessible port (typically any port number over 1024) would +provide a suitable test server. +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the client software, so it is possible that your version of +the client has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B smbd(8) + +.SH DIAGNOSTICS +[This section under construction] + +Most diagnostics issued by the client are logged in a specified log file. The +log file name is specified at compile time, but may be overridden on the +command line. + +The number and nature of diagnostics available depends on the debug level used +by the client. If you have problems, set the debug level to 3 and peruse the +log files. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. + +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +This man page written by Karl Auer (Karl.Auer@anu.edu.au) + +See +.B smb.conf(5) for a full list of contributors and details on how to +submit bug reports, comments etc. diff --git a/docs/manpages/smbd.8 b/docs/manpages/smbd.8 new file mode 100644 index 0000000000..bae41b2c47 --- /dev/null +++ b/docs/manpages/smbd.8 @@ -0,0 +1,407 @@ +.TH SMBD 8 17/1/1995 smbd smbd +.SH NAME +smbd \- provide SMB (aka LanManager) services to clients +.SH SYNOPSIS +.B smbd +[ +.B -D +] [ +.B -a +] [ +.B -d +.I debuglevel +] [ +.B -l +.I log file +] [ +.B -p +.I port number +] [ +.B -O +.I socket options +] [ +.B -s +.I configuration file +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B smbd +is a server that can provide most SMB services. The +server provides filespace and printer services to clients using the SMB +protocol. This is compatible with the LanManager protocol, and can +service LanManager clients. + +An extensive description of the services that the server can provide is given +in the man page for the configuration file controlling the attributes of those +services (see +.B smb.conf(5)). This man page will not describe the services, but +will concentrate on the administrative aspects of running the server. + +Please note that there are significant security implications to running this +server, and +.B smb.conf(5) should be regarded as mandatory reading before proceeding with +installation. + +A session is created whenever a client requests one. Each client gets a copy +of the server for each session. This copy then services all connections made +by the client during that session. When all connections from its client are +are closed, the copy of the server for that client terminates. + +The configuration file is automatically reloaded if it changes. You +can force a reload by sending a SIGHUP to the server. + +.SH OPTIONS +.B -D + +.RS 3 +If specified, this parameter causes the server to operate as a daemon. That is, +it detaches itself and runs in the background, fielding requests on the +appropriate port. + +By default, the server will NOT operate as a daemon. +.RE + +.B -a + +.RS 3 +If this parameter is specified, the log files will be overwritten with each +new connection. By default, the log files will be appended to. +.RE + +.B -d +.I debuglevel +.RS 3 + +debuglevel is an integer from 0 to 5. + +The default value if this parameter is not specified is zero. + +The higher this value, the more detail will be logged to the log files about +the activities of the server. At level 0, only critical errors and serious +warnings will be logged. Level 1 is a reasonable level for day to day running +- it generates a small amount of information about operations carried out. + +Levels above 1 will generate considerable amounts of log data, and should +only be used when investigating a problem. Levels above 3 are designed for +use only by developers and generate HUGE amounts of log data, most of which +is extremely cryptic. +.RE + +.B -l +.I log file + +.RS 3 +If specified, +.I logfile +specifies a base filename into which operational data from the running server +will be logged. + +The default base name is specified at compile time. + +The base name is used to generate actual log file names. For example, if the +name specified was "log", the following files would be used for log data: + +.RS 3 +log.debug (containing debugging information) + +log.in (containing inbound transaction data) + +log.out (containing outbound transaction data) +.RE + +The log files generated are never removed by the server. +.RE + +.B -O +.I socket options +.RS 3 + +See the socket options section of smb.conf(5) for details + +.RE +.B -p +.I port number +.RS 3 + +port number is a positive integer value. + +The default value if this parameter is not specified is 139. + +This number is the port number that will be used when making connections to +the server from client software. The standard (well-known) port number for the +server is 139, hence the default. If you wish to run the server as an ordinary +user rather than as root, most systems will require you to use a port number +greater than 1024 - ask your system administrator for help if you are in this +situation. + +This parameter is not normally specified except in the above situation. +.RE + +.B -s +.I configuration file + +.RS 3 +The default configuration file name is determined at compile time. + +The file specified contains the configuration details required by the server. +The information in this file includes server-specific information such as +what printcap file to use, as well as descriptions of all the services that the +server is to provide. See +.B smb.conf(5) for more information. +.RE + +.SH FILES + +.B /etc/inetd.conf + +.RS 3 +If the server is to be run by the inetd meta-daemon, this file must contain +suitable startup information for the meta-daemon. See the section +"INSTALLATION" below. +.RE + +.B /etc/rc + +.RS 3 +(or whatever initialisation script your system uses) + +If running the server as a daemon at startup, this file will need to contain +an appropriate startup sequence for the server. See the section "INSTALLATION" +below. +.RE + +.B /etc/services + +.RS 3 +If running the server via the meta-daemon inetd, this file must contain a +mapping of service name (eg., netbios-ssn) to service port (eg., 139) and +protocol type (eg., tcp). See the section "INSTALLATION" below. +.RE + +.B /usr/local/smb/smb.conf + +.RS 3 +This file describes all the services the server is to make available to +clients. See +.B smb.conf(5) for more information. +.RE +.RE + +.SH LIMITATIONS + +On some systems smbd cannot change uid back to root after a setuid() call. +Such systems are called "trapdoor" uid systems. If you have such a system, +you will be unable to connect from a client (such as a PC) as two different +users at once. Attempts to connect the second user will result in "access +denied" or similar. + +.SH ENVIRONMENT VARIABLES + +.B PRINTER + +.RS 3 +If no printer name is specified to printable services, most systems will +use the value of this variable (or "lp" if this variable is not defined) +as the name of the printer to use. This is not specific to the server, +however. +.RE + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the server software be installed under the +/usr/local hierarchy, in a directory readable by all, writeable only +by root. The server program itself should be executable by all, as +users may wish to run the server themselves (in which case it will of +course run with their privileges). The server should NOT be +setuid. On some systems it may be worthwhile to make smbd setgid to an +empty group. This is because some systems may have a security hole where +daemon processes that become a user can be attached to with a +debugger. Making the smbd file setgid to an empty group may prevent +this hole from being exploited. This secrity hole and the suggested +fix has only been confirmed on Linux at the time this was written. It +is possible that this hole only exists in Linux, as testing on other +systems has thus far shown them to be immune. + +The server log files should be put in a directory readable and writable only +by root, as the log files may contain sensitive information. + +The configuration file should be placed in a directory readable and writable +only by root, as the configuration file controls security for the services +offered by the server. The configuration file can be made readable by all if +desired, but this is not necessary for correct operation of the server and +is not recommended. A sample configuration file "smb.conf.sample" is supplied +with the source to the server - this may be renamed to "smb.conf" and +modified to suit your needs. + +The remaining notes will assume the following: + +.RS 3 +smbd (the server program) installed in /usr/local/smb + +smb.conf (the configuration file) installed in /usr/local/smb + +log files stored in /var/adm/smblogs +.RE + +The server may be run either as a daemon by users or at startup, or it may +be run from a meta-daemon such as inetd upon request. If run as a daemon, the +server will always be ready, so starting sessions will be faster. If run from +a meta-daemon some memory will be saved and utilities such as the tcpd +TCP-wrapper may be used for extra security. + +When you've decided, continue with either "RUNNING THE SERVER AS A DAEMON" or +"RUNNING THE SERVER ON REQUEST". +.SH RUNNING THE SERVER AS A DAEMON +To run the server as a daemon from the command line, simply put the "-D" option +on the command line. There is no need to place an ampersand at the end of the +command line - the "-D" option causes the server to detach itself from the +tty anyway. + +Any user can run the server as a daemon (execute permissions permitting, of +course). This is useful for testing purposes, and may even be useful as a +temporary substitute for something like ftp. When run this way, however, the +server will only have the privileges of the user who ran it. + +To ensure that the server is run as a daemon whenever the machine is started, +and to ensure that it runs as root so that it can serve multiple clients, you +will need to modify the system startup files. Wherever appropriate (for +example, in /etc/rc), insert the following line, substituting +port number, log file location, configuration file location and debug level as +desired: + +.RS 3 +/usr/local/smb/smbd -D -l /var/adm/smblogs/log -s /usr/local/smb/smb.conf +.RE + +(The above should appear in your initialisation script as a single line. +Depending on your terminal characteristics, it may not appear that way in +this man page. If the above appears as more than one line, please treat any +newlines or indentation as a single space or TAB character.) + +If the options used at compile time are appropriate for your system, all +parameters except the desired debug level and "-D" may be omitted. See the +section "OPTIONS" above. +.SH RUNNING THE SERVER ON REQUEST +If your system uses a meta-daemon such as inetd, you can arrange to have the +smbd server started whenever a process attempts to connect to it. This requires +several changes to the startup files on the host machine. If you are +experimenting as an ordinary user rather than as root, you will need the +assistance of your system administrator to modify the system files. + +You will probably want to set up the name server +.B nmbd +at the same time as +the smbd - refer to the man page +.B nmbd(8). + +First, ensure that a port is configured in the file /etc/services. The +well-known port 139 should be used if possible, though any port may be used. + +Ensure that a line similar to the following is in /etc/services: + +.RS 3 +netbios-ssn 139/tcp +.RE + +Note for NIS/YP users - you may need to rebuild the NIS service maps rather +than alter your local /etc/services file. + +Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event +that you are using a meta-daemon other than inetd, you are on your own). Note +that the first item in this line matches the service name in /etc/services. +Substitute appropriate values for your system in this line (see +.B inetd(8)): + +.RS 3 +netbios-ssn stream tcp nowait root /usr/local/smb/smbd -d1 +-l/var/adm/smblogs/log -s/usr/local/smb/smb.conf +.RE + +(The above should appear in /etc/inetd.conf as a single line. Depending on +your terminal characteristics, it may not appear that way in this man page. +If the above appears as more than one line, please treat any newlines or +indentation as a single space or TAB character.) + +Note that there is no need to specify a port number here, even if you are +using a non-standard port number. + +Lastly, edit the configuration file to provide suitable services. To start +with, the following two services should be all you need: + +.RS 3 +[homes] +.RS 3 + writable = yes +.RE + +[printers] +.RS 3 + writable = no + printable = yes + path = /tmp + public = yes +.RE +.RE + +This will allow you to connect to your home directory and print to any printer +supported by the host (user privileges permitting). +.SH TESTING THE INSTALLATION +If running the server as a daemon, execute it before proceeding. If +using a meta-daemon, either restart the system or kill and restart the +meta-daemon. Some versions of inetd will reread their configuration tables if +they receive a HUP signal. + +If your machine's name is "fred" and your name is "mary", you should now be +able to connect to the service "\\\\fred\\mary". + +To properly test and experiment with the server, we recommend using the +smbclient program (see +.B smbclient(1)). +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the server has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B hosts_access(5), +.B inetd(8), +.B nmbd(8), +.B smb.conf(5), +.B smbclient(1), +.B testparm(1), +.B testprns(1) + +.SH DIAGNOSTICS +[This section under construction] + +Most diagnostics issued by the server are logged in a specified log file. The +log file name is specified at compile time, but may be overridden on the +command line. + +The number and nature of diagnostics available depends on the debug level used +by the server. If you have problems, set the debug level to 3 and peruse the +log files. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. + +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +This man page written by Karl Auer (Karl.Auer@anu.edu.au) + +See +.B smb.conf(5) for a full list of contributors and details on how to +submit bug reports, comments etc. diff --git a/docs/manpages/smbrun.1 b/docs/manpages/smbrun.1 new file mode 100644 index 0000000000..1608d3bb34 --- /dev/null +++ b/docs/manpages/smbrun.1 @@ -0,0 +1,70 @@ +.TH SMBRUN 1 17/1/1995 smbrun smbrun +.SH NAME +smbrun \- interface program between smbd and external programs +.SH SYNOPSIS +.B smbrun +.I shell-command +.SH DESCRIPTION +This program is part of the Samba suite. + +.B smbrun +is a very small 'glue' program, which runs shell commands for +the +.B smbd +daemon (see +.B smbd(8)). + +It first changes to the highest effective user and group ID that it can, +then runs the command line provided using the system() call. This program is +necessary to allow some operating systems to run external programs as non-root. +.SH OPTIONS +.I shell-command + +.RS 3 +The shell command to execute. + +The command should have a fully-qualified path. +.RE +.SH ENVIRONMENT VARIABLES +The PATH variable set for the environment in which +.B smbrun +is executed will affect what executables are located and executed if a +fully-qualified path is not given in the command. + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the +.B smbrun +program be installed under the /usr/local hierarchy, in a directory readable +by all, writeable only by root. The program should be executable by all. +The program should NOT be setuid or setgid! +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the program has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B smbd(8), +.B smb.conf(8) +.SH DIAGNOSTICS +If smbrun cannot be located or cannot be executed by +.B smbd +then appropriate messages will be found in the smbd logs. Other diagnostics are +dependent on the shell-command being run. It is advisable for your shell +commands to issue suitable diagnostics to aid trouble-shooting. +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +This man page was written by Karl Auer (Karl.Auer@anu.edu.au) + +See +.B smb.conf(5) for a full list of contributors and details of how to +submit bug reports, comments etc. diff --git a/docs/manpages/smbstatus.1 b/docs/manpages/smbstatus.1 new file mode 100644 index 0000000000..76dc50cbb5 --- /dev/null +++ b/docs/manpages/smbstatus.1 @@ -0,0 +1,52 @@ +.TH SMBSTATUS 1 17/1/1995 smbstatus smbstatus +.SH NAME +smbstatus \- report on current Samba connections +.SH SYNOPSIS +.B smbstatus +[-d] +[-s +.I configuration file +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B smbstatus +is a very simple program to list the current Samba connections + +Just run the program and the output is self explanatory. You can offer +a configuration filename to override the default. The default is +CONFIGFILE from the Makefile. + +Option +.I -d +gives verbose output. + +.I -p +print a list of smbd processes and exit. Useful for scripting. + +.SH ENVIRONMENT VARIABLES +Not applicable. + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the +.B smbstatus +program be installed under the /usr/local hierarchy, in a directory readable +by all, writeable only by root. The program itself should be executable by all. + +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the program has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B smb.conf(5), +.B smbd(8) + +See +.B smb.conf(5) for a full list of contributors and details on how to +submit bug reports, comments etc. diff --git a/docs/manpages/smbtar.1 b/docs/manpages/smbtar.1 new file mode 100644 index 0000000000..0f1c38c271 --- /dev/null +++ b/docs/manpages/smbtar.1 @@ -0,0 +1,167 @@ +.TH SMBTAR 1 18/2/96 smbtar smbtar +.SH NAME +smbtar \- shell script for backing up SMB shares directly to UNIX tape drive +.SH SYNOPSIS +.B smbtar +.B \-s +.I server +.B [ \-p +.I password +.B ] +.B [ \-x +.I service +.B ] +.B [ \-X ] +.B [ \-d +.I directory +.B ] +.B [ \-u +.I user +.B ] +.B [ \-t +.I tape +.B ] +.B [ \-b +.I blocksize +.B ] +.B [ \-N +.I filename +.B ] +.B [ \-i ] +.B [ \-r ] +.B [ \-l ] +.B [ \-v ] +.I filenames... + +.SH DESCRIPTION +This program is an extension to the Samba suite. + +.B smbtar +is a very small shell script on top of smbclient, which dumps SMB +shares directly to tape. + +.SH OPTIONS +.B \-s +.I server +.RS 3 +The PC that the share resides upon. +.RE + +.B \-x +.I service +.RS 3 +The share name on the PC to connect to. Default: +.I backup. +.RE + +.B \-X +.RS 3 +Exclude mode. Exclude +.I filenames... +from tar create or restore. +.RE + +.B \-d +.I directory +.RS 3 +Change to initial +.I directory +before restoring / backing up files. +.RE + +.B \-v +.RS 3 +Verbose mode. +.RE + +.B \-p +.I password + +.RS 3 +The password to use to access a share. Default: none +.RE + +.B \-u +.I user +.RS 3 +The user id to connect as. Default: UNIX login name. +.RE + +.B \-t +.I tape +.RS 3 +Tape device. May be regular file or tape device. Default: Tape environmental +variable; if not set, a file called +.I tar.out. +.RE + +.B \-b +.I blocksize +.RS 3 +Blocking factor. Defaults to 20. See tar(1) for a fuller explanation. +.RE + +.B \-N +.I filename +.RS 3 +Backup only files newer than filename. Could be used (for example) on a log +file to implement incremental backups. +.RE + +.B \-i +.RS 3 +Incremental mode; tar files are only backed up if they have the +archive bit set. The archive bit is reset after each file is read. +.RE + +.B \-r +.RS 3 +Restore. Files are restored to the share from the tar file. +.RE + +.B \-l +.RS 3 +Debug level. Corresponds to -d flag on smbclient(1). +.RE + +.SH ENVIRONMENT VARIABLES +The TAPE variable specifies the default tape device to write to. May +be overidden with the -t option. + +.SH BUGS +The smbtar script has different options from ordinary tar and tar +called from smbclient. + +.SH CAVEATS +Sites that are more careful about security may not like the way +the script handles PC passwords. Backup and restore work on entire shares, +should work on file lists. + +.SH VERSION +This man page is correct for version 1.9.15p8 of the Samba suite. + +.SH SEE ALSO +.B smbclient +(8), +.B smb.conf +(8) +.SH DIAGNOSTICS +See diagnostics for +.B smbclient +command. + +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +Ricky Poulten (poultenr@logica.co.uk) wrote the tar extension and this +man page. The smbtar script was heavily rewritten and improved by +Martin Kraemer . Many thanks to everyone +who suggested extensions, improvements, bug fixes, etc. + +See +.B smb.conf +(5) for a full list of contributors and details of how to submit bug reports, +comments etc. + diff --git a/docs/manpages/testparm.1 b/docs/manpages/testparm.1 new file mode 100644 index 0000000000..4a0ffcbc48 --- /dev/null +++ b/docs/manpages/testparm.1 @@ -0,0 +1,104 @@ +.TH TESTPARM 1 17/1/1995 testparm testparm +.SH NAME +testparm \- check an smbd configuration file for internal correctness +.SH SYNOPSIS +.B testparm +[ +.I configfilename +[ +.I hostname +.I hostIP +] +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B testparm +is a very simple test program to check an +.B smbd +configuration +file for internal correctness. If this program reports no problems, you can use +the configuration file with confidence that smbd will successfully +load the configuration file. + +Note that this is NOT a guarantee that the services specified in the +configuration file will be available or will operate as expected. + +If the optional host name and host IP address are specified on the +command line, this test program will run through the service entries +reporting whether the specified host has access to each service. +.SH OPTIONS +.I configfilename + +.RS 3 +This is the name of the configuration file to check. +.RE + +.I hostname + +.RS 3 +This is the name of the host to check access on. + +If this parameter is supplied, the +.I hostIP +parameter must also be supplied, or strange things may happen. +.RE + +.I hostIP + +.RS 3 +This is the IP number of the host specified in the previous parameter. + +This number must be supplied if the +.I hostname +parameter is supplied, or strange things may happen. +.RE +.SH FILES +.B smb.conf +.RS 3 +This is usually the name of the configuration file used by smbd. +.RE +.SH ENVIRONMENT VARIABLES +Not applicable. + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the +.B testparm +program be installed under the /usr/local hierarchy, in a directory readable +by all, writeable only by root. The program itself should be executable by all. +The program should NOT be setuid or setgid! +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the program has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B smb.conf(5), +.B smbd(8) +.SH DIAGNOSTICS +The program will issue a message saying whether the configuration file loaded +OK or not. This message may be preceded by errors and warnings if the file +did not load. If the file was loaded OK, the program then dumps all known +service details to stdout. + +If a host name is specified but no host IP number, all bets are off. + +Other messages are self-explanatory. +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +The testparm program and this man page were written by Karl Auer +(Karl.Auer@anu.edu.au) + +See +.B samba(7) for a full list of contributors and details on how to +submit bug reports, comments etc. diff --git a/docs/manpages/testprns.1 b/docs/manpages/testprns.1 new file mode 100644 index 0000000000..f1c3d3ef02 --- /dev/null +++ b/docs/manpages/testprns.1 @@ -0,0 +1,107 @@ +.TH TESTPRNS 1 17/1/1995 testprns testprns +.SH NAME +testprns \- check printer name for validity with smbd +.SH SYNOPSIS +.B testprns +.I printername +[ +.I printcapname +] +.SH DESCRIPTION +This program is part of the Samba suite. + +.B testprns +is a very simple test program to determine whether a given +printer name is valid for use in a service to be provided by +.B smbd. + +"Valid" in this context means "can be found in the printcap specified". This +program is very stupid - so stupid in fact that it would be wisest to always +specify the printcap file to use. +.SH OPTIONS +.I printername + +.RS 3 +The printer name to validate. + +Printer names are taken from the first field in each record in the printcap +file, single printer names and sets of aliases separated by vertical bars +("|") are recognised. Note that no validation or checking of the printcap +syntax is done beyond that required to extract the printer name. It may +be that the print spooling system is more forgiving or less forgiving +than +.B testprns +however if +.B testprns +finds the printer then smbd should do as well. + +.RE + +.I printcapname + +.RS 3 +This is the name of the printcap file to search for the given printer name +in. + +If no printcap name is specified, +.B testprns +will attempt to scan the printcap file specified at compile time +(PRINTCAP_NAME). +.RE +.SH FILES +.B /etc/printcap +.RS 3 +This is usually the default printcap file to scan. See +.B printcap(5)). +.RE +.SH ENVIRONMENT VARIABLES +Not applicable. + +.SH INSTALLATION +The location of the server and its support files is a matter for individual +system administrators. The following are thus suggestions only. + +It is recommended that the +.B testprns +program be installed under the /usr/local hierarchy, in a directory readable +by all, writeable only by root. The program should be executable by all. +The program should NOT be setuid or setgid! +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the program has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. +.SH SEE ALSO +.B printcap(5), +.B smbd(8), +.B smbclient(1) +.SH DIAGNOSTICS +If a printer is found to be valid, the message "Printer name is +valid" will be displayed. + +If a printer is found to be invalid, the message "Printer name +is not valid" will be displayed. + +All messages that would normally be logged during operation of smbd are +logged by this program to the file +.I test.log +in the current directory. The program runs at debuglevel 3, so quite extensive +logging information is written. The log should be checked carefully for errors +and warnings. + +Other messages are self-explanatory. +.SH BUGS +None known. +.SH CREDITS +The original Samba software and related utilities were created by +Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper +of the Source for this project. + +The testprns program and this man page were written by Karl Auer +(Karl.Auer@anu.edu.au) + +See +.B samba(7) for a full list of contributors and details of how to +submit bug reports, comments etc. diff --git a/docs/samba.lsm b/docs/samba.lsm new file mode 100644 index 0000000000..503ba1ec94 --- /dev/null +++ b/docs/samba.lsm @@ -0,0 +1,26 @@ +Begin2 +Title = Samba +Version = 1.8.0 +Desc1 = Samba is a SMB based file and print server for unix. It +Desc2 = provides access to unix file and print services from +Desc3 = SMB compatible clients such as WinNT, WfWg, OS/2 +Desc4 = and Pathworks. It also includes a ftp-style unix client +Desc5 = and a netbios nameserver. +Author = Andrew Tridgell +AuthorEmail = samba-bugs@anu.edu.au +Maintainer = Andrew Tridgell +MaintEmail = samba-bugs@anu.edu.au +Site1 = nimbus.anu.edu.au +Path1 = pub/tridge/samba/ +File1 = samba-latest.tar.gz +FileSize1 = 200K +Required1 = Ansi-C compiler and a TCP/IP network. +CopyPolicy1 = GNU Public License +Keywords = LanManager, SMB, Networking +Comment1 = To join the Samba mailing list send mail to +Comment2 = listproc@listproc.anu.edu.au with a body of +Comment3 = "subscribe samba Your Name" +Entered = October 1994 +EnteredBy = Andrew Tridgell +End + diff --git a/docs/textdocs/BROWSING.txt b/docs/textdocs/BROWSING.txt new file mode 100644 index 0000000000..8a09d2274f --- /dev/null +++ b/docs/textdocs/BROWSING.txt @@ -0,0 +1,145 @@ +BROWSING +======== + +Samba now fully supports browsing. The browsing is supported by nmbd +and is also controlled by options in the smb.conf file (see +smb.conf(5)). + +Samba can act as a browse master for a workgroup, but currently cannot +act as a domain controller. The ability to be a domain controller will +be added in a later version. + +To get browsing to work you need to run nmbd as usual, but will need +to use the "workgroup" option in smb.conf to control what workgroup +Samba becomes a part of. + +The -G option is most useful for simple setups where Samba is browsable +in only one workgroup. In more complex cases the lmhosts file is +better. + +Be very careful setting up your lmhosts file. An incorrectly setup +lmhosts file can have disasterous results for your net! + +A simple lmhosts file might be: + +# This is a simple lmhosts file +# +# This is a host alias. Anyone querying this name +# will get the specified IP +192.0.2.17 SMBDATA +# +# first put ourselves in workgroup MYGROUP using +# our own net address +0.0.0.0 MYGROUP G + +Note in the above that I overrode what workgroup Samba is in using the +G flag. Also note that the 0.0.0.0 address is used, which will be +automatically replaced with the broadcast address for groups, and with +the local IP address for other entries. + +Samba also has a useful option for a Samba server to offer itself for +browsing on another subnet. + +This works by the lmhosts file specifying a broadcast address on the +other network to use to find a browse master for the workgroup. + +For example if you wanted yourself to appear in the workgroup STAFF on +the network which has a broadcast of 192.0.3.255 then this entry would +do the trick: + +# put ourselves in the STAFF workgroup on the other subnet +192.0.3.255 STAFF G + +Notice the G at the end! It is very important you include this as this +entry without the G could cause a broadcast storm! + +If something doesn't work then hopefully the log.nmb file will +help you track down the problem. Try a debug level of 2 or 3 for +finding problems. + +Note that if it doesn't work for you, then you should still be able to +type the server name as \\SERVER in filemanager then hit enter and +filemanager should display the list of available shares. + +Some people find browsing fails because they don't have the global +"guest account" set to a valid account. Remember that the IPC$ +connection that lists the shares is done as guest, and thus you must +have a valid guest account. + +Also, a lot of people are getting bitten by the problem of too many +parameters on the command line of nmbd in inetd.conf. This trick is to +not use spaces between the option and the parameter (eg: -d2 instead +of -d 2), and to not use the -B and -N options. New versions of nmbd +are now far more likely to correctly find your broadcast and network +addess, so in most cases these aren't needed. + +The other big problem people have is that their broadcast address, +netmask or IP address is wrong (specified with the -B, -N and -I +options to nmbd). + +FORCING SAMBA TO BE THE MASTER +============================== + +Who becomes the "master browser" is determined by an election process +using broadcasts. Each election packet contains a number of parameters +which determine what precedence (bias) a host should have in the +election. By default Samba uses a very low precedence and thus loses +elections to just about anyone else. + +If you want Samba to win elections then just set the "os level" global +option in smb.conf to a higher number. It defaults to 0. Using 33 +would make it win all elections over every other system (except other +samba systems!) + +A "os level" of 2 would make it beat WfWg and Win95, but not NTAS. A +NTAS domain controller uses level 32. + +The maximum os level is 255 + +MAKING SAMBA THE DOMAIN MASTER +============================== + +The domain master is responsible for collating the browse lists of +multiple subnets so that browsing can occur between subnets. You can +make samba act as the domain master by setting "domain master = yes" +in smb.conf. By default it will not be a domain master. + +When samba is the domain master and the master browser it will listen +for master announcements from other subnets and then contact them to +synchronise browse lists. + +If you want samba to be the domain master then I suggest you also set +the "os level" high enough to make sure it wins elections. + +NOTIFYING THE DOMAIN CONTROLLER +=============================== + +If you have a domain controller for the domain which Samba is a part +of then you should add the line "domain controller = address" to +smb.conf. "address" can either be a name available via DNS or a IP +address or a broadcast address. If it is a broadcast address then +Samba will look for a domain controller on that network. + +When Samba is the master browser it will regularly contact the domain +controller to synchronise browse lists. + + +NOTE ABOUT BROADCAST ADDRESSES +============================== + +If your network uses a "0" based broadcast address (for example if it +ends in a 0) then you will strike problems. Windows for Workgroups +does not seem to support a 0's broadcast and you will probably find +that browsing and name lookups won't work. + +You have a few options: + +1) change to a 1's broadcast on your unix server. These often end in +.255 (check with your local network guru for details) + +2) set the nmbd broadcast to a 1's based address on the command line using +the -B option. This only works if your network setup listens on both +0s and 1s based broadcasts. The -B option can only control what +address it sends to, not what it listens on. + + diff --git a/docs/textdocs/BUGS.txt b/docs/textdocs/BUGS.txt new file mode 100644 index 0000000000..e0fd695147 --- /dev/null +++ b/docs/textdocs/BUGS.txt @@ -0,0 +1,123 @@ +This file describes how to report Samba bugs. + +>> The email address for bug reports is samba-bugs@anu.edu.au << + +(NOTE: This mail may not be in place yet. If you have troubles with it +then use samba-bugs@arvidsjaur.anu.edu.au) + + +Please take the time to read this file before you submit a bug +report. Also, please see if it has changed between releases, as I +may be changing the bug reporting mechanism sometime soon. + +Please also do as much as you can yourself to help track down the +bug. I only develop Samba in my spare time and I receive far more mail +about it than I can possibly answer, so you have a much higher chance +of an answer and a fix if you send me a "developer friendly" bug +report that lets me fix it fast. + +Do not assume that if you post the bug to the comp.protocols.smb +newsgroup that I will read it. I do read all postings to the samba +mailing list (see the README). If you suspect that your problem is not +a bug but a configuration problem then it is better to send it to the +Samba mailing list, as there are (at last count) 1900 other users on +that list that may be able to help you. + +You may also like to look though the recent mailing list archives, +which are conveniently accessible on the Samba web pages +at http://lake.canberra.edu.au/pub/samba/ + + +GENERAL INFO +------------ + +Before submitting a bug report check your config for silly +errors. Look in your log files for obvious messages that tell you that +you've misconfigured something and run testparm to test your config +file for correct syntax. + +If you include part of a log file with your bug report then be sure to +annotate it with exactly what you were doing on the client at the +time, and exactly what the results were. + + +DEBUG LEVELS +------------ + +If the bug has anything to do with Samba behaving incorrectly as a +server (like refusing to open a file) then the log files will probably +be very useful. Depending on the problem a log level of between 3 and +10 showing the problem may be appropriate. A higher level givesmore +detail, but may use too much disk space. + +To set the debug level use "log level =" in your smb.conf. You may +also find it useful to set the log level higher for just one machine +and keep separate logs for each machine. To do this use: + +log file = /usr/local/samba/lib/log.%m +include = /usr/local/samba/lib/smb.conf.%m + +then create a file "/usr/local/samba/lib/smb.conf.machine" where +"machine" is the name of the client you wish to debug. In that file +put any smb.conf commands you want, for example "log level=" may be +useful. This also allows you to experiment with different security +systems, protocol levels etc on just one machine. + + +INTERNAL ERRORs +--------------- + +If you get a "INTERNAL ERROR" message in your log files it means that +Samba got an unexpected signal while running. It is probably a +segmentation fault and almost certainly means a bug in Samba (unless +you have faulty hardware or system software) + +If the message came from smbd then it will probably be accompanied by +a message which details the last SMB message received by smbd. This +info is often very useful in tracking down the problem so please +include it in your bug report. + +You should also detail how to reproduce the problem, if +possible. Please make this reasonably detailed. + +You may also find that a core file appeared in a "corefiles" +subdirectory of the directory where you keep your samba log +files. This file is the most useful tool for tracking down the bug. To +use it you do this: + +gdb smbd core + +adding appropriate paths to smbd and core so gdb can find them. If you +don't have gdb then try "dbx". Then within the debugger use the +command "where" to give a stack trace of where the problem +occurred. Include this in your mail. + +If you known any assembly language then do a "disass" of the routine +where the problem occurred (if its in a library routine then +disassemble the routine that called it) and try to work out exactly +where the problem is by looking at the surrounding code. Even if you +don't know assembly then incuding this info in the bug report can be +useful. + + +ATTACHING TO A RUNNING PROCESS +------------------------------ + +Unfortunately some unixes (in particular some recent linux kernels) +refuse to dump a core file if the task has changed uid (which smbd +does often). To debug with this sort of system you could try to attach +to the running process using "gdb smbd PID" where you get PID from +smbstatus. Then use "c" to continue and try to cause the core dump +using the client. The debugger should catch the fault and tell you +where it occurred. + + +PATCHES +------- + +The best sort of bug report is one that includes a fix! If you send me +patches please use "diff -u" format if your version of diff supports +it, otherwise use "diff -c4". Make sure your do the diff against a +clean version of the source and let me know exactly what version you +used. + diff --git a/docs/textdocs/DIAGNOSIS.txt b/docs/textdocs/DIAGNOSIS.txt new file mode 100644 index 0000000000..6681bdc4bc --- /dev/null +++ b/docs/textdocs/DIAGNOSIS.txt @@ -0,0 +1,237 @@ +DIAGNOSING YOUR SAMBA SERVER +============================ + +This file contains a list of tests you can perform to validate your +Samba server. It also tells you what the likely cause of the problem +is if it fails any one of these steps. If it passes all these tests +then it is probably working fine. + +You should do ALL the tests, in the order shown. I have tried to +carefully choose them so later tests only use capabilities verified in +the earlier tests. + +I would welcome additions to this set of tests. Please mail them to +samba-bugs@anu.edu.au + +If you send me an email saying "it doesn't work" and you have not +followed this test procedure then you should not be surprised if I +ignore your email. + + +ASSUMPTIONS +----------- + +In all of the tests I assume you have a Samba server called BIGSERVER +and a PC called ACLIENT. I also assume the PC is running windows for +workgroups with a recent copy of the microsoft tcp/ip stack. The +procedure is similar for other types of clients. + +I also assume you know the name of a available share in your +smb.conf. I will assume this share is called "tmp". You can add a +"tmp" share like by adding the following to smb.conf: + +[tmp] + comment = temporary files + path = /tmp + read only = yes + + +THESE TESTS ASSUME VERSION 1.9.15 OR LATER OF THE SAMBA SUITE. SOME +COMMANDS SHOWN DID NOT EXIST IN EARLIER VERSIONS + + +TEST 1: +------- + +run the command "testparm". If it reports any errors then your +smb.conf configuration file is faulty. + + +TEST 2: +------- + +run the command "ping BIGSERVER" from the PC and "ping ACLIENT" from +the unix box. If you don't get a valid response then your TCP/IP +software is not correctly installed. + +Note that you will need to start a "dos prompt" window on the PC to +run ping. + +If you get a message saying "host not found" or similar then your DNS +software or /etc/hosts file is not correctly setup. It is possible to +run samba without DNS entries for the server and client, but I assume +you do have correct entries for the remainder of these tests. + + +TEST 3: +------- + +run the command "smbclient -L BIGSERVER -U%" on the unix box. You +should get a list of available shares back. + +If you get a error message containing the string "Bad password" then +you probably have either an incorrect "hosts allow", "hosts deny" or +"valid users" line in your smb.conf, or your guest account is not +valid. Check what your guest account is using "testparm" and +temporarily remove any "hosts allow", "hosts deny", "valid users" or +"invalid users" lines. + +If you get a "connection refused" response then the smbd server could +not be run. If you installed it in inetd.conf then you probably edited +that file incorrectly. If you installed it as a daemon then check that +it is running, and check that the netbios-ssn port is in a LISTEN +state using "netstat -a". + +If you get a "session request failed" then the server refused the +connection. If it says "your server software is being unfriendly" then +its probably because you have invalid command line parameters to smbd, +or a similar fatal problem with the initial startup of smbd. Also +check your config file for syntax errors with "testparm". + +TEST 4: +------- + +run the command "nmblookup -B BIGSERVER __SAMBA__". You should get the +IP address of your Samba server back. + +If you don't then nmbd is incorrectly installed. Check your inetd.conf +if yu run it from there, or that the daemon is running and listening +to udp port 137. + +One common problem is that many inetd implementations can't take many +parameters on the command line. If this is the case then create a +one-line script that contains the right parameters and run that from +inetd. + +TEST 5: +------- + +run the command "nmblookup -B ACLIENT '*'" + +You should get the PCs IP address back. If you don't then the client +software on the PC isn't installed correctly, or isn't started, or you +got the name of the PC wrong. Note that you probably won't get a "node +status response" from the PC due to a bug in the microsoft netbios +nameserver implementation (it responds to the wrong port number). + +TEST 6: +------- + +run the command "nmblookup -d 2 '*'" + +This time we are trying the same as the previous test but are trying +it via a broadcast to the default broadcast address. A number of +Netbios/TCPIP hosts on the network should respond, although Samba may +not catch all of the responses in the short time it listens. You +should see "got a positive name query response" messages from several +hosts. + +If this doesn't give a similar result to the previous test then +nmblookup isn't correctly getting your broadcast address through its +automatic mechanism. In this case you should experiment with the -B +option which allows you to manually specify the broadcast address, +overriding the automatic detection. You should try different broadcast +addresses until your find the one that works. It will most likely be +something like a.b.c.255 as microsoft tcpip stacks only listen on 1's +based broadcast addresses. If you get stuck then ask your local +networking guru for help (and show them this paragraph). + +If you find you do need the -B option (ie. the automatic detection +doesn't work) then you should add the -B option with the right +broadcast address for your network to the command line of nmbd in +inetd.conf or in the script you use to start nmbd as a daemon. Once +you do this go back to the "nmblookup __SAMBA__ -B BIGSERVER" test to +make sure you have it running properly. + +If your PC and server aren't on the same subnet then you will need to +use the -B option to set the broadcast address to the that of the PCs +subnet. + +TEST 7: +------- + +run the command "smbclient '\\BIGSERVER\TMP'". You should then be +prompted for a password. You should use the password of the account +you are logged into the unix box with. If you want to test with +another account then add the -U option to the command +line. + +Once you enter the password you should get the "smb>" prompt. If you +don't then look at the error message. If it says "invalid network +name" then the service "tmp" is not correctly setup in your smb.conf. + +If it says "bad password" then the likely causes are: + +- you have shadow passords (or some other password system) but didn't +compile in support for them in smbd +- your "valid users" configuration is incorrect +- you have a mixed case password and you haven't enabled the "password +level" option at a high enough level +- the "path =" line in smb.conf is incorrect. Check it with testparm + +Once connected you should be able to use the commands "dir" "get" +"put" etc. Type "help " for instructions. You should +especially check that the amount of free disk space shown is correct +when you type "dir". + + +TEST 8: +------- + +On the PC type the command "net view \\BIGSERVER". You will need to do +this from within a "dos prompt" window. You should get back a list of +available shares on the server. + +If you get a "network name not found" or similar error then netbios +name resolution is not working. This is usually caused by a problem in +nmbd. To overcome it you could do one of the following (you only need +to choose one of them): + +- fixup the nmbd installation +- add the IP address of BIGSERVER to the "wins server" box in the +advanced tcp/ip setup on the PC. +- enable windows name resolution via DNS in the advanced section of +the tcp/ip setup +- add BIGSERVER to your lmhosts file on the PC. + +If you get a "invalid network name" or "bad password error" then the +same fixes apply as they did for the "smbclient -L" test above. In +particular, make sure your "hosts allow" line is correct (see the man +pages) + + +TEST 9: +-------- + +run the command "net use x: \\BIGSERVER\TMP". You should be prompted +for a password then you should get a "command completed successfully" +message. If not then your PC software is incorrectly installed or your +smb.conf is incorrect. make sure your "hosts allow" and other config +lines in smb.conf are correct. + +It's also possible that the server can't work out what user name to +connect you as. To see if this is the problem add the line "user = +USERNAME" to the [tmp] section of smb.conf where "USERNAME" is the +username corresponding to the password you typed. If you find this +fixes things you may need the username mapping option. + + +TEST 10: +-------- + +From file manager try to browse the server. Your samba server should +appear in the browse list of your local workgroup (or the one you +specified in the Makefile). You should be able to double click on the +name of the server and get a list of shares. If you get a "invalid +password" error when you do then you are probably running WinNT and it +is refusing to browse a server that has no encrypted password +capability and is in user level security mode. + + +Still having troubles? +---------------------- + +Try the mailing list or newsgroup, or use the tcpdump-smb utility to +sniff the problem. + + diff --git a/docs/textdocs/DNIX.txt b/docs/textdocs/DNIX.txt new file mode 100644 index 0000000000..51005e6ec8 --- /dev/null +++ b/docs/textdocs/DNIX.txt @@ -0,0 +1,69 @@ +DNIX has a problem with seteuid() and setegid(). These routines are +needed for Samba to work correctly, but they were left out of the DNIX +C library for some reason. + +For this reason Samba by default defines the macro NO_EID in the DNIX +section of includes.h. This works around the problem in a limited way, +but it is far from ideal, some things still won't work right. + +To fix the problem properly you need to assemble the following two +functions and then either add them to your C library or link them into +Samba. + +put this in the file setegid.s: + + .globl _setegid +_setegid: + moveq #47,d0 + movl #100,a0 + moveq #1,d1 + movl 4(sp),a1 + trap #9 + bccs 1$ + jmp cerror +1$: + clrl d0 + rts + + +put this in the file seteuid.s: + + .globl _seteuid +_seteuid: + moveq #47,d0 + movl #100,a0 + moveq #0,d1 + movl 4(sp),a1 + trap #9 + bccs 1$ + jmp cerror +1$: + clrl d0 + rts + +after creating the above files you then assemble them using + +as seteuid.s +as setegid.s + +that should produce the files seteuid.o and setegid.o + +then you need to add these to the LIBSM line in the DNIX section of +the Samba Makefile. Your LIBSM line will then look something like this: + +LIBSM = setegid.o seteuid.o -ln + +You should then remove the line: + +#define NO_EID + +from the DNIX section of includes.h + +Then recompile and try it out! + +Note that this file was derived from an email from Peter Olsson +. I don't have DNIX myself, so you're probably better +off contacting Peter if you have problems. + +Andrew + diff --git a/docs/textdocs/DOMAIN.txt b/docs/textdocs/DOMAIN.txt new file mode 100644 index 0000000000..31e19675fa --- /dev/null +++ b/docs/textdocs/DOMAIN.txt @@ -0,0 +1,68 @@ +Samba now supports domain logons and network logon scripts. The +support is still experimental, but it seems to work. + +The support is also not complete. Samba does not yet support the +sharing of the SAM database with other systems yet, or remote +administration. Support for these kind of things should be added +sometime in the future. + +The domain support only works for WfWg and Win95 clients. Support for +NT and OS/2 clients is still being worked on. + +Using these features you can make your clients verify their logon via +the Samba server and make clients run a batch file when they logon to +the network. The latter is particularly useful. + +To use domain logons you need to do the following: + +1) Setup nmbd and smbd and configure the smb.conf so that Samba is +acting as the master browser. See INSTALL.txt and BROWSING.txt for +details. + +2) create a share called [netlogon] in your smb.conf. This share should +be readable by all users, and probably should not be writeable. This +share will hold your network logon scripts. + +For example I have used: + + [netlogon] + path = /data/dos/netlogon + writeable = no + guest ok = yes + + +3) in the [global] section of smb.conf set the following: + + domain logons = yes + logon script = %U.bat + +the choice of batch file is, of course, up to you. The above would +give each user a separate batch file as the %U will be changed to +their username automatically. The other standard % macros may also be +used. You can make the btch files come from a subdirectory by using +soemthing like: + + logon script = scripts\%U.bat + +4) create the batch files to be run when the user logs in. If the batch +file doesn't exist then no batch file will be run. + +In the batch files you need to be careful to use DOS style cr/lf line +endings. If you don't then DOS may get confused. I suggest you use a +DOS editor to remotely edit the files if you don't know how to produce +DOS style files under unix. + +5) Use smbclient with the -U option for some users to make sure that +the \\server\NETLOGON share is available, the batch files are visible +and they are readable by the users. + +6) you will probabaly find that your clients automatically mount the +\\SERVER\NETLOGON share as drive z: while logging in. You can put some +useful programs there to execute from the batch files. + + +NOTE: You must be using "security = user" or "security = server" for +domain logons to work correctly. Share level security won't work +correctly. + + diff --git a/docs/textdocs/ENCRYPTION.txt b/docs/textdocs/ENCRYPTION.txt new file mode 100644 index 0000000000..046b473e9a --- /dev/null +++ b/docs/textdocs/ENCRYPTION.txt @@ -0,0 +1,333 @@ + LanManager / Samba Password Encryption. + --------------------------------------- + +With the development of LanManager compatible password encryption for +Samba, it is now able to validate user connections in exactly the same +way as a LanManager or Windows NT server. + +This document describes how the SMB password encryption algorithm +works and what issues there are in choosing whether you want to use +it. You should read it carefully, especially the part about security +and the "PROS and CONS" section. + +How does it work ? +------------------ + + LanManager encryption is somewhat similar to UNIX password +encryption. The server uses a file containing a hashed value of a +users password. This is created by taking the users paintext +password, capitalising it, and either truncating to 14 bytes (or +padding to 14 bytes with null bytes). This 14 byte value is used as +two 56 bit DES keys to encrypt a 'magic' eight byte value, forming a +16 byte value which is stored by the server and client. Let this value +be known as the *hashed password*. + +When a client (LanManager, Windows for WorkGroups, Windows 95 or +Windows NT) wishes to mount a Samba drive (or use a Samba resource) it +first requests a connection and negotiates the protocol that the client +and server will use. In the reply to this request the Samba server +generates and appends an 8 byte, random value - this is stored in the +Samba server after the reply is sent and is known as the *challenge*. + +The challenge is different for every client connection. + +The client then uses the hashed password (16 byte value described +above), appended with 5 null bytes, as three 56 bit DES keys, each of +which is used to encrypt the challenge 8 byte value, forming a 24 byte +value known as the *response*. + +In the SMB call SMBsessionsetupX (when user level security is +selected) or the call SMBtconX (when share level security is selected) +the 24 byte response is returned by the client to the Samba server. + +The Samba server then reproduces the above calculation, using it's own +stored value of the 16 byte hashed password (read from the smbpasswd +file - described later) and the challenge value that it kept from the +negotiate protocol reply. It then checks to see if the 24 byte value it +calculates matches the 24 byte value returned to it from the client. + +If these values match exactly, then the client knew the correct +password (or the 16 byte hashed value - see security note below) and +is this allowed access. If not then the client did not know the +correct password and is denied access. + +Note that the Samba server never knows or stores the cleartext of the +users password - just the 16 byte hashed function derived from it. Also +note that the cleartext password or 16 byte hashed value are never +transmitted over the network - thus increasing security. + +IMPORTANT NOTE ABOUT SECURITY +----------------------------- + +The unix and SMB password encryption techniques seem similar on the +surface. This similarity is, however, only skin deep. The unix scheme +typically sends clear text passwords over the nextwork when logging +in. This is bad. The SMB encryption scheme never sends the cleartext +password over the network but it does store the 16 byte hashed value +on disk. This is also bad. Why? Because the 16 byte hashed value is a +"password equivalent". You cannot derive the users password from it, +but it could potentially be used in a modified client to gain access +to a server. This would require considerable technical knowledge on +behalf of the attacker but is perfectly possible. You should thus +treat the smbpasswd file as though it contained the cleartext +passwords of all your users. Its contents must be kept secret, and the +file should be protected accordingly. + +Ideally we would like a password scheme which neither requires plain +text passwords on the net or on disk. Unfortunately this is not +available as Samba is stuck with being compatible with other SMB +systems (WinNT, WfWg, Win95 etc). + + +PROS AND CONS +------------- + +There are advantages and disadvantages to both schemes. + +Advantages of SMB Encryption: +----------------------------- + +- plain text passwords are not passed across the network. Someone using +a network sniffer cannot just record passwords going to the SMB server. + +- WinNT doesn't like talking to a server that isn't using SMB +encrypted passwords. It will refuse to browse the server if the server +is also in user level security mode. It will insist on promting the +user for the password on each connection, which is very annoying. The +only things you can do to stop this is to use SMB encryption. + +Advantages of non-encrypted passwords: +-------------------------------------- + +- plain text passwords are not kept on disk. + +- uses same password file as other unix services such as login and +ftp + +- you are probably already using other services (such as telnet and +ftp) which send plain text passwords over the net, so not sending them +for SMB isn't such a big deal. + +- the SMB encryption code in Samba is new and has only had limited +testing. We have tried hard to make it secure but in any new +implementation of a password scheme there is the possability of an +error. + + +The smbpasswd file. +------------------- + + In order for Samba to participate in the above protocol it must +be able to look up the 16 byte hashed value given a user name. +Unfortunately, as the UNIX password value is also a one way hash +function (ie. it is impossible to retrieve the cleartext of the users +password given the UNIX hash of it) then a separate password file +containing this 16 byte value must be kept. To minimise problems with +these two password files, getting out of sync, the UNIX /etc/passwd and +the smbpasswd file, a utility, mksmbpasswd.sh, is provided to generate +a smbpasswd file from a UNIX /etc/passwd file. + +To generate the smbpasswd file from your /etc/passwd file use the +following command :- + +cat /etc/passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd + +If you are running on a system that uses NIS, use + +ypcat passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd + +The mksmbpasswd.sh program is found in the Samba source directory. By +default, the smbpasswd file is stored in :- + +/usr/local/samba/private/smbpasswd + +The owner of the /usr/local/samba/private directory should be set to +root, and the permissions on it should be set to :- + +r-x------ + +The command + +chmod 500 /usr/local/samba/private + +will do the trick. Likewise, the smbpasswd file inside the private +directory should be owned by root and the permissions on is should be +set to + +rw------- + +by the command :- + +chmod 600 smbpasswd. + +The format of the smbpasswd file is + +username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Long name:user home dir:user shell + +Although only the username, uid, and XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +sections are significant and are looked at in the Samba code. + +It is *VITALLY* important that there by 32 'X' characters between the +two ':' characters - the smbpasswd and Samba code will fail to validate +any entries that do not have 32 characters between ':' characters. + +When the password file is created all users have password entries +consisting of 32 'X' characters. By default this disallows any access +as this user. When a user has a password set, the 'X' characters change +to 32 ascii hexadecimal digits (0-9, A-F). These are an ascii +representation of the 16 byte hashed value of a users password. + +To set a user to have no password (not recommended), edit the file +using vi, and replace the first 11 characters with the asci text + +NO PASSWORD + +Eg. To clear the password for user bob, his smbpasswd file entry would +look like : + +bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:Bob's full name:/bobhome:/bobshell + +If you are allowing users to use the smbpasswd command to set their own +passwords, you may want to give users NO PASSWORD initially so they do +not have to enter a previous password when changing to their new +password (not recommended). + +Note : This file should be protected very carefully. Anyone with +access to this file can (with enough knowledge of the protocols) gain +access to your SMB server. The file is thus more sensitive than a +normal unix /etc/passwd file. + +The smbpasswd Command. +---------------------- + + The smbpasswd command maintains the 32 byte password field in +the smbpasswd file. If you wish to make it similar to the unix passwd +or yppasswd programs, install it in /usr/local/samba/bin (or your main +Samba binary directory) and make it setuid root. + +Note that if you do not do this then the root user will have to set all +users passwords. + +To set up smbpasswd as setuid root, change to the Samba binary install +directory and then type (as root) : + +chown root smbpasswd +chmod 4555 smbpasswd + +If smbpasswd is installed as setuid root then you would use it as +follows. + +smbpasswd +Old SMB password: +New SMB Password: < type new value > +Repeat New SMB Password: < re-type new value > + +If the old value does not match the current value stored for that user, +or the two new values do not match each other, then the password will +not be changed. + +If invoked by an ordinary user it will only allow the user to change +his or her own Samba password. + +If run by the root user smbpasswd may take an optional argument, +specifying the user name whose SMB password you wish to change. Note +that when run as root smbpasswd does not prompt for or check the old +password value, thus allowing root to set passwords for users who have +forgotten their passwords. + +smbpasswd is designed to work in the same way and be familiar to UNIX +users who use the passwd or yppasswd commands. + +NOTE. As smbpasswd is designed to be installed as setuid root I would +appreciate it if everyone examined the source code to look for +potential security flaws. A setuid program, if not written properly can +be an open door to a system cracker. Please help make this program +secure by reporting all problems to me (the author, Jeremy Allison). + +My email address is :- + +jra@vantive.com + +Setting up Samba to support LanManager Encryption. +-------------------------------------------------- + +This is a very brief description on how to setup samba to support +password encryption. More complete instructions will probably be added +later. + +1) get and compile the libdes libraries. the source is available from +nimbus.anu.edu.au in pub/tridge/libdes/libdes.tar.92-10-13.gz + +2) enable the encryption stuff in the Samba makefile, making sure you +point it to the libdes library and include file (it needs des.h) +The entries you need to uncomment are the four lines after the comment :- + +# This is for SMB encrypted (lanman) passwords. + +Note that you may have to change the variable DES_BASE to +point at the place where you installed the DES library. + +3) compile and install samba as usual + +4) f your system can't compile the module getsmbpass.c then remove the +-DSMBGETPASS define from the Makefile. + +5) enable encrypted passwords in smb.conf by adding the line +"encrypt passwords = yes" in the [global] section + +6) create the initial smbpasswd password file in the place you +specified in the Makefile. A simple way to do this based on your +existing Makefile (assuming it is in a reasonably standard format) is +like this: + +cat /etc/passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd + +Change ownership of private and smbpasswd to root. + +chown -R root /usr/local/samba/private + +Set the correct permissions on /usr/local/samba/private + +chmod 500 /usr/local/samba/private + +Set the correct permissions on /usr/local/samba/private/smbpasswd + +chmod 600 /usr/local/samba/private/smbpasswd + +note that the mksmbpasswd.sh script is in the samba source directory. + +If this fails then you will find that you will need entries that look +like this: + +# SMB password file. +tridge:148:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Andrew Tridgell:/home/tridge:/bin/tcsh + +note that the uid and username fields must be right. Also, you must get +the number of X's right (there should be 32). + +If you wish, install the smbpasswd program as suid root. + +chown root /usr/local/samba/bin/smbpasswd +chmod 4555 /usr/local/samba/bin/smbpasswd + +7) set the passwords for users using the smbpasswd command. For +example, as root you could do "smbpasswd tridge" + +8) try it out! + +Note that you can test things using smbclient, as it also now supports +encryption. + +NOTE TO USA Sites that Mirror Samba +----------------------------------- + +The DES library is considered a munition in the USA. Under US Law it is +illegal to export this software, or to put it in a freely available ftp +site. + +Please do not mirror the DES directory from the site on nimbus.anu.edu.au + +Thank you, + +Jeremy Allison. + diff --git a/docs/textdocs/HINTS.txt b/docs/textdocs/HINTS.txt new file mode 100644 index 0000000000..953650bdd3 --- /dev/null +++ b/docs/textdocs/HINTS.txt @@ -0,0 +1,202 @@ +Here are some random hints that you may find useful. These really +should be incorporated in the main docs someday. + + +---------------------- +HINT: Always test your smb.conf with testparm before using it + +If your smb.conf file is invalid then samba will fail to load. Run +testparm over it before you install it just to make sure there aren't +any basic syntax or logical errors. + + +---------------------- +HINT: Try printing with smbclient first + +If you have problems printing, test with smbclient first. Just connect using +"smbclient '\\server\printer' -P" and use the "print" command. + +Once this works, you know that Samba is setup correctly for printing, +and you should be able to get it to work from your PCs. + +This particularly helps in getting the "print command" right. + + +---------------------- +HINT: Mount cdroms with conv=binary + +Some OSes (notably Linux) default to auto detection of file type on +cdroms and do cr/lf translation. This is a very bad idea when use with +Samba. It causes all sorts of stuff ups. + +To overcome this problem use conv=binary when mounting the cdrom +before exporting it with Samba. + + +---------------------- +HINT: Convert between unix and dos text formats + +Jim barry has written an excellent drag-and-drop cr/lf converter for +windows. Just drag your file onto the icon and it converts the file. + +Get it from +ftp://nimbus.anu.edu.au/pub/tridge/samba/contributed/fixcrlf.zip + +---------------------- +HINT: Use the "username map" option + +If the usernames used on your PCs don't match those used on the unix +server then you will find the "username map" option useful. + +----------------------- +HINT: Use "security = user" in [global] + +If you have the same usernames on the unix box and the PCs or have +mapped them with the "username map" option then choose "security = +user" in the [global] section of smb.conf. + +This will mean your password is checked only when you first connect, +and subsequent connections to printers, disks etc will go more +smoothly and much faster. + +The main problem with "security = user" if you use WfWg is that you +will ONLY be able to connect as the username that you log into WfWg +with. This is because WfWg silently ignores the password field in the +connect drive dialog box if the server is in user security mode. + +------------------------ +HINT: Make your printers not "guest ok" + +If your printers are not "guest ok" and you are using "security = +user" and have matching unix and PC usernames then you will attach to +the printer without trouble as your own username. This will mean you +will be able to delete print jobs (in 1.8.06 and above) and printer +accounting will be possible. + + +----------------------- +HINT: Use a sensible "guest" account + +Even if all your services are not available to "guest" you will need a +guest account. This is because the browsing is done as guest. In many +cases setting "guest account = ftp" will do the trick. Using the +default guest account or "guest account = nobody" will give problems on +many unixes. If in doubt create another account with minimal +privilages and use it instead. Your users don't need to know the +password of the guest account. + + +----------------------- +HINT: Use the latest TCP/IP stack from microsoft if you use Windows +for workgroups. + +The early TCP/IP stacks had lots of bugs. + +Microsoft has released an incremental upgrade to their TCP/IP 32-Bit +VxD drivers. The latest release can be found on their ftp site at +ftp.microsoft.com, located in /peropsys/windows/public/tcpip/wfwt32.exe. +There is an update.txt file there that describes the problems that were +fixed. New files include WINSOCK.DLL, TELNET.EXE, WSOCK.386, VNBT.386, +WSTCP.386, TRACERT.EXE, NETSTAT.EXE, and NBTSTAT.EXE. + + +----------------------- +HINT: nmbd can act as a "WINS" server + +By default SMB clients use broadcasts to find shares. Recent clients +(such as WfWg) can use a "wins" server instead, whcih reduces your +broadcast traffic and allows you to find names across routers. + +Just point your WfWg, Win95 and NT clients at the Samba box in the WINS option. + +Note: nmbd does not support all WINS operations. Anyone out there have +a spec they could send me? + +----------------------- +HINT: you may need to delete your .pwl files when you change password. + +WfWg does a lousy job with passwords. I find that if I change my +password on either the unix box or the PC the safest thing to do is to +delete the .pwl files in the windows directory. The PC will complain about not finding the files, but will soon get over it, allowing you to enter the new password. + +If you don't do this you may find that WfWg remembers and uses the old +password, even if you told it a new one. + +Often WfWg will totally ignore a password you give it in a dialog box. + +---------------------- +HINT: Using MS Access + +Here are some notes on running MS-Access on a Samba drive from Stefan +Kjellberg + +1. Opening a database in 'exclusive' mode does NOT work. Samba ignores + r/w/share modes on file open. + +2. Make sure that you open the database as 'shared' and to 'lock modified + records' + +3. Of course locking must be enabled for the particular share (smb.conf) + + +--------------------- +HINT: password cacheing in WfWg + +Here is a hint from michael@ecel.uwa.edu.au (Michael Simmons): + +In case people where not aware. There is a program call admincfg.exe +on the last disk (disk 8) of the WFW 3.11 disk set. To install it +type EXPAND A:\ADMINCFG.EX_ C:\WINDOWS\ADMINCFG.EXE Then add an icon +for it via the "Progam Manager" "New" Menu. This program allows you +to control how WFW handles passwords. ie disable Password Caching etc +for use with "security = user" + + +-------------------- +HINT: file descriptor limits + +If you have problems with the limits on the number of open files you +can edit local.h to fix it. + +-------------------- +HINT: HPUX initgroups() problem + +here is a hint from Frank Wales [frank@arcglade.demon.co.uk]: + +HP's implementation of supplementary groups is, er, non-standard (for +hysterical reasons). There are two group files, /etc/group and +/etc/logingroup; the system maps UIDs to numbers using the former, but +initgroups() reads the latter. Most system admins who know the ropes +symlink /etc/group to /etc/logingroup (hard link doesn't work for reasons +too stupid to go into here). initgroups() will complain if one of the +groups you're in in /etc/logingroup has what it considers to be an invalid +ID, which means outside the range [0..UID_MAX], where UID_MAX is (I think) +60000 currently on HP-UX. This precludes -2 and 65534, the usual 'nobody' +GIDs. + +Perhaps you could suggest to users that, if they encounter this problem, +they make sure that the programs that are failing to initgroups() be +run as users not in any groups with GIDs outside the allowed range. + +This is documented in the HP manual pages under setgroups(2) and passwd(4). + + +--------------------- +HINT: Patch your SCO system + +If you run SCO Unix then you may need to get important TCP/IP patches +for Samba to work correctly. Try + +Paul_Davis@mindlink.bc.ca writes: + + I was having problems with Accpac using 1.9.02 on SCO Unix. One + posting function reported corrupted data. After installing uod385a, + the problem went away (a restore from backup and then another + run-thru). + + It appears that the uod385a update for SCO may be fairly important for + a lot of different DOS and Windows software under Samba. + + uod385a can be found at ftp.sco.com /SLS/uod385a.Z and uod385a.ltr.Z. + + diff --git a/docs/textdocs/INSTALL.sambatar b/docs/textdocs/INSTALL.sambatar new file mode 100644 index 0000000000..388e2a3eb6 --- /dev/null +++ b/docs/textdocs/INSTALL.sambatar @@ -0,0 +1,27 @@ + +Please see the readme and the man page for general info. + +1) Follow the samba installation instructions. + +2) If all goes well, test it out by creating a share on your PC (called +backup for example) then doing something like, + + ./smbtar -s mypc -t /dev/rmt/0ubn -x backup + +substituting whatever your tape drive is for the -t option, or set your +tape environmental variable. + +If all does not go well, feel free to mail the author (poultenr@logica.co.uk) +about bug reports / help / money / pizza / etc. + +3) Read the man page and the NOTES file for more information + +4) Work smbtar into your usual nightly backup scheme (presuming you +have one :-}). + + +NOTE: + +If you have problems with smbtar then it's probably best to contact the +author Ricky Poulten (poultenr@logica.co.uk). + diff --git a/docs/textdocs/PROJECTS b/docs/textdocs/PROJECTS new file mode 100644 index 0000000000..cf903f2c6d --- /dev/null +++ b/docs/textdocs/PROJECTS @@ -0,0 +1,96 @@ + Samba Projects Directory + ======================== + + +>>>>> NOTE: THIS FILE IS NOW VERY OUT OF DATE <<<<< + + +This is a list of who's working on what in Samba. It's not guaranteed +to be uptodate or accurate but I hope it will help us getting +coordinated. + +If you are working on something to do with Samba and you aren't here +then please let me know! Also, if you are listed below and you have +any corrections or updates then please let me know. + +Email contact: +samba-bugs@anu.edu.au + +======================================================================== +Documentation and FAQ + +Docs and FAQ files for the Samba suite of software. + +Contact Karl.Auer@anu.edu.au + +Mark Preston is now working on a set of formatted docs for Samba. +Contact mpreston@sghms.ac.uk + +Docs are currently up to date with version, 1.7.07. FAQ being added to +as questions arise. + +Status last updated 27th September 1994 +======================================================================== + +======================================================================== +Netbeui support + +This aims to produce patches so that Samba can be used with clients +that do not have TCP/IP. It will try to remain as portable as possible. + +Contact Brian.Onn@Canada.Sun.COM (Brian Onn) + +The project is just startup up. + +Status last updated 4th October 1994 +======================================================================== + +======================================================================== +Smbfs + +A mountable smb filesystem for Linux using the userfs userspace filesystem + +Contact lendecke@namu01.gwdg.de (Volker Lendecke) + +Currently this is at version 0.2. It works but is really only for +people with some knowledge and experience of Linux kernel hacking. + +Status last updated 23rd August 1994 +======================================================================== + +======================================================================== +Nmbd + +Aims to produce a complete rfc1001/1002 implementation. The current +nmbd is a partial implementation. + +Contact Fabrice Cetre (cetre@ifhpserv.insa-lyon.fr) + +Status last updated 23rd August 1994 +======================================================================== + +======================================================================== +Admin Tool + +Aims to produce a nice smb.conf editor and other useful tools for +administering a Samba system. + +Contact: Steve Brown (steve@unicorn.dungeon.com) + +In the design phase. + +Status last updated 4th September 1994 +======================================================================== + + +======================================================================== +Lanman Client. + +Contact: john@amanda.xs4all.nl (John Stewart) + +Aims to produce a reliable LANMAN Client implementation for LINUX, +and possibly other variations of UNIX. Project ably started by +Tor Lillqvist; tml@hemuli.tte.vtt.fi + +Status last updated 17th January 1995 +======================================================================== diff --git a/docs/textdocs/Passwords.txt b/docs/textdocs/Passwords.txt new file mode 100644 index 0000000000..e06876feca --- /dev/null +++ b/docs/textdocs/Passwords.txt @@ -0,0 +1,42 @@ +NOTE ABOUT PASSWORDS +==================== + +Unix systems use a wide variety of methods for checking the validity +of a password. This is primarily controlled with the Makefile defines +mentioned in the Makefile. + +Also note that some clients (notably WfWg) uppercase the password +before sending it. The server tries the password as it receives it and +also after lowercasing it. + +The Samba server can also be configured to try different +upper/lowercase combinations. This is controlled by the [global] +parameter "password level". A level of N means to try all combinations +up to N uppercase characters in the password. A high value can chew a +fair bit of CPU time and can lower the security of your system. Do not +use this options unless you really need it - the time taken for +password checking can become so high that clients time out. + +If you do use the "password level" option then you might like to use +-DUFC_CRYPT in your Makefile. On some machine this makes password +checking _much_ faster. This is also useful if you use the @group +syntax in the user= option. + +If your site uses AFS (the Andrew File System), you can use the AFS section +in the Makefile. This will first attempt to authenticate a username and +password to AFS. If that succeeds, then the associated AFS rights will be +granted. Otherwise, the password checking routine falls back to whatever +Unix password checking method you are using. Note that the AFS code is +only written and tested for AFS 3.3 and later. + + +SECURITY = SERVER +================= + +Samba can use a remote server to do it's username/password +validation. This allows you to have one central machine (for example a +NT box) control the passwords for the Unix box. + +See the section on "security =" in smb.conf(5) for details. + + diff --git a/docs/textdocs/README.DCEDFS b/docs/textdocs/README.DCEDFS new file mode 100644 index 0000000000..f84b84bb68 --- /dev/null +++ b/docs/textdocs/README.DCEDFS @@ -0,0 +1,79 @@ +============================================================================= + + Basic DCE/DFS Support for SAMBA 1.9.13 + + Jim Doyle 06-02-95 + +============================================================================= + +Functionality: +-------------- + + Per-instance authentication for DCE/DFS. + +Missing Functionality in this Implementation: +--------------------------------------------- + + * No automatic refresh of credentials + + To do so would not be that hard.. One could simply + stash the clear-text key in memory, spawn a key management + thread to wake up right before credentials expire and + refresh the login context. + + * No UNIX Signals support (SIGCLD, SIGPIPE, SIGHUP, SIGBUS, SIGSEGV) + + + There is no support for signal processing in Samba daemons + that need to authenticate with DCE. The explanation for this + is that the smbd is linked against thread-safe libraries in + order to be able to use DCE authentication mechanisms. + Because smbd uses signal() and fork(), it represents the + worst case scenario for DCE portability. In order + to properly support signals in a forked server environment, + some rework of smbd is needed in order to properly + construct, shutdown and reconstruct asynchronous signal + handling threads and synchronous signal traps across the + parent and child. I have not had contiguous time to work + on it, I expect it to be a weeks worth of work to cleanly + integrate thread-safe signal handing into the code and + test it. Until I can get to this task, I will leave it up + to someone adventurous enough to engineer it and negotiate + with Andrew to integrate the changes into the mainline branch. + + The lack of full signal support means that you cannot + rely upon SIGHUP-ing the parent daemon to refresh + the configuration data. Likewise, you cannot take advantage + of the builtin SIGBUS/SIGSEGV traps to diagnose failures. + You will have to halt Samba in order to make changes + and then have them take effect. + + The SMBD server as it stands is suitable to use if you + already have experience with configuring and running + SAMBA. + +Tested Platforms: +----------------- + + HP-UX 9.05 / HP-UX DCE 1.2.1 + AIX 3.2.5 / AIX DCE/6000 1.3 + DEC OSF-1 3.0 / DEC DCE 1.3 + +Building: +--------- + + - Uncomment the the appropriate block in the Makefile + for the platform you wish to build on. + + - Samples of Samba server configuration files for our + DFS environment are included in samples.dcedfs/ + + + +Bugs, Suggestions, etc.. +-------------------------- + + Please post them to the mailing list. + That way I will see them and they will become part of + the archives so others can share the knowledge. + diff --git a/docs/textdocs/README.jis b/docs/textdocs/README.jis new file mode 100644 index 0000000000..2ac6716a6f --- /dev/null +++ b/docs/textdocs/README.jis @@ -0,0 +1,124 @@ +● samba 日本語対応について + +1. 目的 + + 日本語対応は、 + + (1) MS-Windows 上で、漢字ファイル名をどうしても扱う必要のあるアプリケーションがちゃ + んと動作する。例えば、MS-WORD 5 などは、インストール時に漢字のファイル名を勝手 + につけてしまいます。こういった場合にちゃんと対応できるようにする。 + + (2) UNIX は、最近ではほとんどのものが 8 bits のファイル名をサポートしていますが、 + 中には、これをサポートしていないものもあります。このような場合でも、(1)の目的 + が満足できるようにする。 + + を目的としています。そのため、日本語対応は、必要最小限しか行なっておりません。 + +2. 利用方法 + +(1) 追加したパラメータ + + smb.conf ファイルの global セクションに以下のパラメータを設定できるようにしました。 + + [global] + .... + coding system = <コード系> + + ここで指定されたコード系が UNIX 上のファイルシステムのファイル名のコードになります。 + 設定できるものは、次のようになっています。 + + sjis: SHIFT JIS (MS 漢字コード) + euc: EUC コード + hex: 7 bits の ASCII コード以外のコードを以下の形式で表す方式です。例えば、 + 'オフィス' という名前は、':83:49:83:74:83:42:83:58' のように、':' の後に２桁 + の16進数を続ける形式になります。 + ここで、':' を他の文字に変更したい場合は、hex の後ろにその文字を指定します。 + 例えば、@を変わりに使いたい場合は、'hex@'のように指定します。 + JIS コードについては、以下の表を参照して下さい。 + ┌───┬────┬────┬────┬────┬────┬─────────┐ + │指定 │漢字開始│漢字終了│カナ開始│カナ終了│英数開始│備考 │ + ├───┼────┼────┼────┼────┼────┼─────────┤ + │jis7 │\E$B │\E(J │0x0e │0x0f │\E(J │jis 7単位符号 │ + │junet │\E$B │\E(J │\E(I │\E(J │\E(J │7bits コード │ + │jis8 │\E$B │\E(J │-- │-- │\E(J │jis 8単位符号 │ + │j7bb │\E$B │\E(B │0x0e │0x0f │\E(B │ │ + │j7bj │\E$B │\E(J │0x0e │0x0f │\E(J │jis7と同じ │ + │j7bh │\E$B │\E(H │0x0e │0x0f │\E(H │ │ + │j7@b │\E$@ │\E(B │0x0e │0x0f │\E(B │ │ + │j7@j │\E$@ │\E(J │0x0e │0x0f │\E(J │ │ + │j7@h │\E$@ │\E(H │0x0e │0x0f │\E(H │ │ + │j8bb │\E$B │\E(B │-- │-- │\E(B │ │ + │j8bj │\E$B │\E(J │-- │-- │\E(J │jis8と同じ │ + │j8bh │\E$B │\E(H │-- │-- │\E(H │ │ + │j8@b │\E@@ │\E(B │-- │-- │\E(B │ │ + │j8@j │\E$@ │\E(J │-- │-- │\E(J │ │ + │j8@h │\E$@ │\E(H │-- │-- │\E(H │ │ + │jubb │\E$B │\E(B │\E(I │\E(B │\E(B │ │ + │jubj │\E$B │\E(J │\E(I │\E(J │\E(J │junetと同じ │ + │jubh │\E$B │\E(H │\E(I │\E(H │\E(H │ │ + │ju@b │\E$@ │\E(B │\E(I │\E(B │\E(B │ │ + │ju@j │\E$@ │\E(J │\E(I │\E(J │\E(J │ │ + │ju@h │\E$@ │\E(H │\E(I │\E(H │\E(H │ │ + └───┴────┴────┴────┴────┴────┴─────────┘ + + いずれの場合も、すでに存在している名前に対しては、漢字の開始終了シーケンスは、以下 + のものを認識します。 + 漢字の始まり: \E$B か \E$@ + 漢字の終り: \E(J か \E(B か \E(H + +(2) smbclient のオプション + + クライアントプログラムでも、漢字や仮名を含んだファイルを扱えるように、次のオプション + を追加しました。 + + -t <ターミナルコード系> + + ここで、<ターミナルコード系>に指定できるものは、上の<コード系>と同じものです。 + +(3) デフォルト + + デフォルトのコード系は、コンパイル時に決まります。 + +3. コンパイル時の設定 + + Makefile に設定する項目を以下に示します。 + +(1) KANJI フラグ + + コンパイルオプションに -DKANJI=\"コード系\" を指定します。このコード系は 2. で指 + 定するものと同じです。例えば、-DKANJI=\"euc\" をFLAGSM に設定すると UNIX 上のファ + イル名は、EUC コードになります。ここで指定したコード系は、サーバ及びクライアント + プログラムのデフォルトに値なります。 + +3. 制限事項 + +(1) 漢字コード + smbd を動作させるホストの UNIX がサポートしていない漢字コードは、利用できないことが + あります。変な動作をするようなら hex の指定をするのが良いでしょう。 + +(2) smbclient コマンド + シフトコードなどの関係で、漢字や仮名を含んだファイル名の ls の表示が乱れることがあり + ます。 + +(3) ワイルドカードについて + ちゃんとしたスペックがよくわからなかったのですが、一応、DOS/V の動作と同じ動作を行な + うようになっています。 + +4. 障害等のレポートについて + + 日本語のファイル名に関して、文字化け等の障害があれば、私にレポートして頂ければ幸いで +す。ただし、オリジナルからの問題点や質問については、オリジナルの作者へ直接問い合わせる +か、もしくはメーリングリストなどへレポートするようにして下さい。 + +5. その他 + + hex 形式の変換方法は、 + + 大木＠大塚・筑波 氏 + + が作られたコードを利用しています。 + +1994年10月28日 第１版 +1995年 8月16日 第２版 +藤田 崇 fujita@ainix.isac.co.jp + diff --git a/docs/textdocs/README.sambatar b/docs/textdocs/README.sambatar new file mode 100644 index 0000000000..26829952eb --- /dev/null +++ b/docs/textdocs/README.sambatar @@ -0,0 +1,15 @@ + +This is version 1.4 of my small extension to samba that allows PC shares +to be backed up directly to a UNIX tape. It only has been tested under +Solaris 2.3, Linux 1.1.59 and DG/UX 5.4r3.10 with version 1.9.13 of samba. + +See the file INSTALL for installation instructions, and +the man page and NOTES file for some basic usage. Please let me know if you +have any problems getting it to work under your flavour of Unix. + +This is only (yet another) intermediate version of sambatar. +This version also comes with an extra gift, zen.bas, written in +microsoft qbasic by a colleague. It is (apparently) based on a 70s +British sci-fi series known as Blake's 7. If you have any questions +about this program, or any suggestions (e.g. what about servillan.bas +?), feel free to mail the author (of zen.bas) greenm@lilhd.logica.com. diff --git a/docs/textdocs/SCO.txt b/docs/textdocs/SCO.txt new file mode 100644 index 0000000000..1b3801471f --- /dev/null +++ b/docs/textdocs/SCO.txt @@ -0,0 +1,12 @@ +There is an annoying TCPIP bug in SCO Unix. This causes orruption when +transferring files with Samba. + +Geza Makay (makayg@math.u-szeged.hu) sends this information: + +The patch you need is UOD385 Connection Drivers SLS. It is available from +SCO (ftp.sco.com, directory SLS, files uod385a.Z and uod385a.ltr.Z). + +You do not need anything else but the above patch. It installs in seconds, +and corrected the Excel problem. We also had some other minor problems (not +only with Samba) that disappeared by installing this patch. + diff --git a/docs/textdocs/SMBTAR.notes b/docs/textdocs/SMBTAR.notes new file mode 100644 index 0000000000..a23cbf2b32 --- /dev/null +++ b/docs/textdocs/SMBTAR.notes @@ -0,0 +1,40 @@ + +Intro +----- + +sambatar is just a small extension to the smbclient program distributed with +samba. A basic front end shell script, smbtar, is provided as an interface +to the smbclient extensions. + +Extensions +---------- + +This release adds the following extensions to smbclient, + +tar [c|x] filename + creates or restores from a tar file. The tar file may be a tape +or a unix tar file. tar's behaviour is modified with the newer and tarmode +commands. + +tarmode [full|inc|reset|noreset] + With no arguments, tarmode prints the current tar mode (by default full, +noreset). In full mode, every file is backed up during a tar command. +In incremental, only files with the dos archive bit set are backed up. +The archive bit is reset if in reset mode, or left untouched if in noreset. +In reset mode, the share has to be writable, which makes sambatar even +less secure. An alternative might be to use tarmode inc noreset which +would implement an "expanding incremental" backup (which some may prefer +anyway). + +setmode filename + This is a "freebie" - nothing really to do with sambatar. This +is a crude attrib like command (only the other way around). Setmode string +is a combination of +-rhsa. So for example -rh would reset the read only +bit on filename. + +newer filename + This is in fact part of the 1.9.13 samba distribution, but comes +into its own with sambatar. This causes tar (or get, mget, etc) to +only copy files newer than the specified file name. Could be used +against the previous nights (or whatever) log file to implement incremental +backups. \ No newline at end of file diff --git a/docs/textdocs/Speed.txt b/docs/textdocs/Speed.txt new file mode 100644 index 0000000000..5dfd70323b --- /dev/null +++ b/docs/textdocs/Speed.txt @@ -0,0 +1,272 @@ +This file tries to outline the ways to improve the speed of a Samba server. + +Andrew Tridgell +January 1995 + + +COMPARISONS +----------- + +The Samba server uses TCP to talk to the client. Thus if you are +trying to see if it performs well you should really compare it to +programs that use the same protocol. The most readily available +programs for file transfer that use TCP are ftp or another TCP based +SMB server. + +If you want to test against something like a NT or WfWg server then +you will have to disable all but TCP on either the client or +server. Otherwise you may well be using a totally different protocol +(such as Netbeui) and comparisons may not be valid. + +Generally you should find that Samba performs similarly to ftp at raw +transfer speed. It should perform quite a bit faster than NFS, +although this very much depends on your system. + +Several people have done comparisons between Samba and Novell, NFS or +WinNT. In some cases Samba performed the best, in others the worst. I +suspect the biggest factor is not Samba vs some other system but the +hardware and drivers used on the various systems. Given similar +hardware Samba should certainly be competitive in speed with other +systems. + + +SOCKET OPTIONS +-------------- + +There are a number of socket options that can greatly affect the +performance of a TCP based server like Samba. + +The socket options that Samba uses are settable both on the command +line with the -O option, or in the smb.conf file. + +The "socket options" section of the smb.conf manual page describes how +to set these and gives recommendations. + +Getting the socket options right can make a big difference to your +performance, but getting them wrong can degrade it by just as +much. The correct settings are very dependent on your local network. + +The socket option TCP_NODELAY is the one that seems to make the +biggest single difference for most networks. Many people report that +adding "socket options = TCP_NODELAY" doubles the read performance of +a Samba drive. The best explanation I have seen for this is that the +Microsoft TCP/IP stack is slow in sending tcp ACKs. + + +READ SIZE +--------- + +The option "read size" affects the overlap of disk reads/writes with +network reads/writes. If the amount of data being transferred in +several of the SMB commands (currently SMBwrite, SMBwriteX and +SMBreadbraw) is larger than this value then the server begins writing +the data before it has received the whole packet from the network, or +in the case of SMBreadbraw, it begins writing to the network before +all the data has been read from disk. + +This overlapping works best when the speeds of disk and network access +are similar, having very little effect when the speed of one is much +greater than the other. + +The default value is 16384, but very little experimentation has been +done yet to determine the optimal value, and it is likely that the best +value will vary greatly between systems anyway. A value over 65536 is +pointless and will cause you to allocate memory unnecessarily. + + +MAX XMIT +-------- + +At startup the client and server negotiate a "maximum transmit" size, +which limits the size of nearly all SMB commands. You can set the +maximum size that Samba will negotiate using the "max xmit = " option +in smb.conf. + +It defaults to 65536 bytes (the maximum), but it is possible that some +clients may perform better with a smaller transmit unit. Trying values +of less than 2048 is likely to cause severe problems. + +In most cases the default is the best option. + + +LOCKING +------- + +By default Samba does not implement strict locking on each read/write +call (although it did in previous versions). If you enable strict +locking (using "strict locking = yes") then you may find that you +suffer a severe performance hit on some systems. + +The performance hit will probably be greater on NFS mounted +filesystems, but could be quite high even on local disks. + + +SHARE MODES +----------- + +Some people find that opening files is very slow. This is often +because of the "share modes" code needed to fully implement the dos +share modes stuff. You can disable this code using "share modes = +no". This will gain you a lot in opening and closing files but will +mean that (in some cases) the system won't force a second user of a +file to open the file read-only if the first has it open +read-write. For many applications that do their own locking this +doesn't matter, but for some it may. + +LOG LEVEL +--------- + +If you set the log level (also known as "debug level") higher than 2 +then you may suffer a large drop in performance. This is because the +server flushes the log file after each operation, which can be very +expensive. + + +WIDE LINKS +---------- + +The "wide links" option is now enabled by default, but if you disable +it (for better security) then you may suffer a performance hit in +resolving filenames. The performance loss is lessened if you have +"getwd cache = yes", which is now the default. + + +READ RAW +-------- + +The "read raw" operation is designed to be an optimised, low-latency +file read operation. A server may choose to not support it, +however. and Samba makes support for "read raw" optional, with it +being enabled by default. + +In some cases clients don't handle "read raw" very well and actually +get lower performance using it than they get using the conventional +read operations. + +So you might like to try "read raw = no" and see what happens on your +network. It might lower, raise or not affect your performance. Only +testing can really tell. + + +WRITE RAW +--------- + +The "write raw" operation is designed to be an optimised, low-latency +file write operation. A server may choose to not support it, +however. and Samba makes support for "write raw" optional, with it +being enabled by default. + +Some machines may find "write raw" slower than normal write, in which +case you may wish to change this option. + +READ PREDICTION +--------------- + +Samba can do read prediction on some of the SMB commands. Read +prediction means that Samba reads some extra data on the last file it +read while waiting for the next SMB command to arrive. It can then +respond more quickly when the next read request arrives. + +This is disabled by default. You can enable it by using "read +prediction = yes". + +Note that read prediction is only used on files that were opened read +only. + +Read prediction should particularly help for those silly clients (such +as "Write" under NT) which do lots of very small reads on a file. + +Samba will not read ahead more data than the amount specified in the +"read size" option. It always reads ahead on 1k block boundaries. + + +MEMORY MAPPING +-------------- + +Samba supports reading files via memory mapping them. One some +machines this can give a large boost to performance, on others it +makes not difference at all, and on some it may reduce performance. + +To enable you you have to recompile Samba with the -DUSE_MMAP=1 option +on the FLAGS line of the Makefile. + +Note that memory mapping is only used on files opened read only, and +is not used by the "read raw" operation. Thus you may find memory +mapping is more effective if you disable "read raw" using "read raw = +no". + + +SLOW CLIENTS +------------ + +One person has reported that setting the protocol to COREPLUS rather +than LANMAN2 gave a dramatic speed improvement (from 10k/s to 150k/s). + +I suspect that his PC's (386sx16 based) were asking for more data than +they could chew. I suspect a similar speed could be had by setting +"read raw = no" and "max xmit = 2048", instead of changing the +protocol. Lowering the "read size" might also help. + + +SLOW LOGINS +----------- + +Slow logins are almost always due to the password checking time. Using +the lowest practical "password level" will improve things a lot. You +could also enable the "UFC crypt" option in the Makefile. + +CLIENT TUNING +------------- + +Often a speed problem can be traced to the client. The client (for +example Windows for Workgroups) can often be tuned for better TCP +performance. + +See your client docs for details. In particular, I have heard rumours +that the WfWg options TCPWINDOWSIZE and TCPSEGMENTSIZE can have a +large impact on performance. + +Also note that some people have found that setting DefaultRcvWindow in +the [MSTCP] section of the SYSTEM.INI file under WfWg to 3072 gives a +big improvement. I don't know why. + +My own experience wth DefaultRcvWindow is that I get much better +performance with a large value (16384 or larger). Other people have +reported that anything over 3072 slows things down enourmously. One +person even reported a speed drop of a factor of 30 when he went from +3072 to 8192. I don't know why. + +It probably depends a lot on your hardware, and the type of unix box +you have at the other end of the link. + +MY RESULTS +---------- + +Some people want to see real numbers in a document like this, so here +they are. I have a 486sx33 client running WfWg 3.11 with the 3.11b +tcp/ip stack. It has a slow IDE drive and 20Mb of ram. It has a SMC +Elite-16 ISA bus ethernet card. The only WfWg tuning I've done is to +set DefaultRcvWindow in the [MSTCP] section of system.ini to 16384. My +server is a 486dx3-66 running Linux. It also has 20Mb of ram and a SMC +Elite-16 card. You can see my server config in the examples/tridge/ +subdirectory of the distribution. + +I get 490k/s on reading a 8Mb file with copy. +I get 441k/s writing the same file to the samba server. + +Of course, there's a lot more to benchmarks than 2 raw throughput +figures, but it gives you a ballpark figure. + +I've also tested Win95 and WinNT, and found WinNT gave me the best +speed as a samba client. The fastest client of all (for me) is +smbclient running on another linux box. Maybe I'll add those results +here someday ... + + +COMMENTS +-------- + +If you've read this far then please give me some feedback! Which of +the above suggestions worked for you? + +Mail the samba mailing list or samba-bugs@anu.edu.au diff --git a/docs/textdocs/Support.txt b/docs/textdocs/Support.txt new file mode 100644 index 0000000000..d71bdaf7b3 --- /dev/null +++ b/docs/textdocs/Support.txt @@ -0,0 +1,376 @@ +The Samba Consultants List +========================== + +This is a list of people who are prepared to install and support Samba. +Note that in most countries nobody should admit to "supplying" Samba, since +there is then an implied warranty with possibly onerous legal obligations. +Just downloading and installing it isn't supply in this sense, but advertising +"run our Samba for best results" may be so. + +Being on this list does not imply any sort of endorsement by anyone, it is just +provided in the hope that it will be useful. + +If you want to be added to the list, or want your entry modified then +contact the address below. They are currently listed in the +order that they were received. If it gets too big we may organise it +by region. Please make sure to include a header line giving the region +and country, eg CANBERRA - AUSTRALIA. + +You can contact the maintainers at samba-bugs@anu.edu.au + + +------------------------------------------------------------------------------ +BRISBANE - AUSTRALIA + +Brett Worth +Select Computer Technology - Brisbane +431 Logan Road +Stones Corner QLD 4120 +E-Mail: brett@sct.com.au +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +CANBERRA - AUSTRALIA + +Paul Blackman (ictinus@lake.canberra.edu.au, Ph. 06 2012518) is +available for consultation. Paul's Samba background is with +Solaris 2.3/4 and WFWG/Win95 machines. Paul is also the maintainer +of the SAMBA Web Pages. +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +READING - ENGLAND + +Philip Hands | E-Mail: info@hands.com +Philip Hands Computing Ltd. | Tel: +44 1734 476287 Fax: 1734 474655 +Unit 1, Cherry Close, Caversham, Reading RG4 8UP UK + +Samba experience: SVR4,SVR3.2 & Linux <--> WfWg, W3.1, OS2 and MS-LanMan +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +ILLONOIS - USA + +Information One, Inc. +736 Hinman Ave, Suite 2W +Evanston, IL 60202 +708-328-9137 708-328-0117 FAX +info@info1.com + +Providing custom Internet and networking solutions. +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +Olympic Peninsula Consulting; 1241 Lansing Ave W., Bremerton, WA 98312-4343 +telephone 1+ 360 792 6938; mailto:opc@aa.net; http://www.aa.net/~opc; +Unix Systems and TCP/IP Network design, programming, and administration. +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +SolutionS R Us has been in business for 3+ years providing viable 3rd +party support in system/network administration. With our own Linux +distribution which we're constantly improving to make it the best and +using it to provide total solutions for companies which are open to +using Linux. + +Mauro DePalma +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +BIELEFELD - GERMANY + +I am located in Bielefeld/Germany and have been doing Unix consultancy +work for the past 8 years throughout Germany and the rest of Europe. I +can be contacted by email at or via phone at +49 521 +9225922 or telefax at +49 521 9225924. +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +CANBERRA - AUSTRALIA + +Ben Elliston +Faculty of Information Sciences and Engineering +University of Canberra AUSTRALIA +E-mail: ben@ise.canberra.edu.au (Uni) +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +PALERMO - ITALY + +Francesco Cardinale +E-Mail: cardinal@palermo.italtel.it +Samba experience: SVR3.2, SOLARIS, ULTRIX, LINUX <--> DOS LAN-MAN, WFW +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +SYDNEY - AUSTRALIA + +John Terpstra - Aquasoft (jht@aquasoft.com.au) +Business: +612 524 4040 +Home: +612 540 3154 +Shoephone: +612 414 334422 (aka 0414 334422) +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +ONTARIO - CANADA + +Strata Software Limited, Kanata Ontario CANADA +Tel: +1 (613) 591-1922 Fax: +1 (613) 591-3485 +Email: sales@strataware.com WWW: http://www.strataware.com/ + +Strata Software Limited is a software development and consulting group +specializing in data communications (TCP/IP and OSI), X.400, X.500 and +LDAP, and X.509-based security. We have Samba experience with Windows NT, +Windows 95, and Windows for Workgroups clients with Linux, Unixware +(SVR4), and HP-UX servers. +------------------------------------------------------------------------------ + +----------------------------------------------------------------------- +SYDNEY - AUSTRALIA + +We are a Unix & Windows developer with a consulting & support component. +In business since 1981 with experience on Sun, hp, sgi, IBM rs6000 plus +Windows, NT and Win95, Using Samba since September 94. +CodeSmiths, 22 Darley Road, MANLY 2095 NSW; 977 1979; fax: 977 2116 +philm@esi.com.au (Australia; New South Wales; SYDNEY; North East) +----------------------------------------------------------------------- + +------------------------------------------------------------------------------ +EDINBUGH - SCOTLAND + +Charlie Hussey email charlie@edina.demon.co.uk +Edina Software Limited tel 0131 657 1129 +4 James Street fax 0131 669 9092 +Edinburgh EH15 2DS + +SAMBA experience: SCO UNIX <=> WfWg +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +LONDON - ENGLAND + +Mark H. Preston, +Network Analyst, | Email : mpreston@sghms.ac.uk +Computer Unit, | Tel : +44 (0)181 725-5434 +St. George's Hospital Med School, | Fax : +44 (0)181 725-3583 +London SW17 ORE. | WWW : http://www.sghms.ac.uk + +Samba Experience: +Server: Solaris 2.3 & 2.4, Irix 5.2 & 5.3 +Client: WinNT, Win95, WfWg, Win3.1, Ms-LanMan, DHCP support +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +SYDNEY - AUSTRALIA + +Pacific ESI has used and installed Samba since 1.6 on a range +of machines running SunOS, BSD/OS, SCO/UNIX, HP/UX, and Solaris, +and WfWG and Windows95. The largest system worked on to date +involved an Australia wide network of machines with PCs and SUNs +at the various nodes. The in-house testing site is a wide area +network with three sites, remotely connected with PPP and with +SUN servers at each site to all of which are connected several +PCs running mainly WfWG. + +Stefan Kjellberg Pacific Engineering Systems +International +info@eram.esi.com.au Voice:+61-2-9063377 +... Fax:+61-2-9063468 +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +CHANTILLY - USA + +Intelligent Decisions, Inc. +ATTN: Richard Bullington +14121 Parke Long Ct. #104 +Chantilly, VA 22021 +U.S.A. +(703) 803-8070 +rbullington@intdec.com + +Samba experience: Linux, DEC ULTRIX <=> WFWG 3.11, Windows NT 3.5 +Specializing in World Wide Web related UNIX-to-PC connectivity. +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ +FORT COLLINS, CO - USA + +Granite Computing Solutions +ATTN: Brian Grossman +Box 270103 +Fort Collins, CO 80527-0103 +U.S.A. +(970) 225-2370 +granite@fortnet.org + +Information services, including WfWG, NT, Apple <=> Unix interoperability. + +Our standard advertisement says: + +> Unix workstations, servers and custom systems < +>> WWW and Unix education << +>>> Enterprise and departmental computing solutions <<< +>>> Backup & restore <<< +>> Software forensics << +> Data translation < +------------------------------------------------------------------------------ + +---------------------------------------------------------- +Adelaide, Australia + +NS Computer Software and Services P/L +PO Box 86 +Ingle Farm +SA 5098 + +Contact: Richard Sharpe + Ph: +61-8-281-0063 (08-281-0063) AH + FAX:+61-8-250-2080 (08-250-2080) + +Experience with: ULTRIX, Digital UNIX, SunOS, WfW 3.11, Win95, WNT 3.51 + +---------------------------------------------------------- + +---------------------------------------------------------- +TECTONIC LIMITED +WESTWOOD +78 LOUGHBOROUGH ROAD +QUORN +LEICESTERSHIRE +LE12 8DX + +TELEPHONE 01509-620922 +FAX 01509-620933 + +CONTACT DAVID ROBINSON + +WE ARE UNIX ORIENTATED BUT ALSO SPECIALISE IN PC TO UNIX COMMUNICATIONS, WE +KNOW AND UNDERSTAND PC-NFS, (HENCE OUR INTEREST IN SAMBA). +WE SUPPORT SUNOS, SOLARIS 1.X AND 2.X, HP-UX 9.0 AND 10.0, OSF (or DEC UNIX, +whichever you prefer), WinNT, WfWG and Win95. + +WE ARE ALREADY TALKING TO A COUPLE OF VERY LARGE SAMBA USERS HERE IN THE UK. +WE WOULD LIKE TO SUPPORT THEM (AND MANY MORE), WOULD YOU PLEASE CONTACT ME ON: +david@tectonic.demon.co.uk +---------------------------------------------------------- + +---------------------------------------------------------- +MIAMI, FL - USA + +Swaney & Associates, Inc. +ATTN: Stephen Swaney + 2543 Lincoln Avenue + Miami, Florida 33133 + U.S.A + (305) 860-0570 + +Specializing in: + High Availability system & networks + UNIX to PC connectivity + Market Data systems + Messaging Systems (Sendmail & Microsoft Exchange) +---------------------------------------------------------- + +------------------------------------------------------------------------------ +NEW JERSEY - USA + +William J. Maggio +LAN & Computer Integrators, Inc. +242 Old New Brunswick Road Email: bmaggio@lci.com +Suite 440 Voice: 908-981-1991 +Piscataway, NJ 08855 Fax : 908-981-1858 + + Specializing in Internet connectivity and security, Sun integration and + high speed, enterprise network design and deployment. +------------------------------------------------------------------------------ + +FAREHAM - ENGLAND + +High Field Technology Ltd +Little Park Farm Road, Segensworth West, +Fareham, Hants PO15 5SJ, UK. +sales@hft.co.uk tel +44 148 957 0111 fax +44 148 957 0555 + +Company skills: Real time hardware and software systems + +Samba experience: BSD/OS, Linux, LynxOS <==> WFWG, NT + +------------------------------------------------------------------------------ + +----------------------------------------------------------------------- +QUEBEC - CANADA + +Dataden Computer Systems +Attn: Danny Arseneau +arseneau@parkmed.com +895 2nd Avenue +Ile Bizard, Quebec +Canada, H9C 1K3 +Tel: (514)891-2293 +Fax: (514)696-0848 + +Dataden is company that specializes in Unix--TCP/IP networking. +We have over 15 years of experience. We have been installing, +configuring and maintaining Samba for clients for 1-1/2 years now. We +have samba installations on Linx, SunOS and DEC OSF. Our biggest site +has 4 Suns and 3 Linux servers running Samba which are serving a network +of about 50 PC's running WFWg and Win95. +----------------------------------------------------------------------- + +----------------------------------------------------------------------- +CALIFORNIA - USA + +Ron Halstead +Open Systems Consulting +3098-4 Lakemont Drive +San Ramon, CA 94583 (San Francisco Bay Area) +(510) 735-7529 +halstead@ix.netcom.com +----------------------------------------------------------------------- + + +----------------------------------------------------------------------- +MELBOURNE - AUSTRALIA + +Michael Ciavarella +Cybersoruce Pty Ltd. +8/140 Queen Street +Melbourne VIC 3000 +Phone: +61-3-9642-5997 +Fax: +61-3-9642-5998 +Email: mikec@cyber.com.au +WWW: http://www.cyber.com.au + +Cybersource specialises in TCP/IP network integration and Open Systems +administration. Cybersource is an Australian-owned and operated +company, with clients including some of Australia's largest financial, +petrochemical and state government organisations. +----------------------------------------------------------------------- + +----------------------------------------------------------------------- +SOUTHERN CALIFORNIA - USA + +Michael St. Laurent +Serving Los Angeles and Orange Counties. Please contact via email. +rowl@earthlink.net +Michael St. Laurent +Hartwell Corporation +------------------------------------------------------------------------------ +WASHINGTON DC METRO - USA + +Asset Software, Inc. has been running Samba since the 1.6 release on various +platforms, including SunOS 4.x, Solaris 2.x, IRIX 4.x and 5.x, Linux 1.1x, +1.2x, and 1.3x, and BSD UNIX 4.3 and above. We specialize in small office +network solutions and provide services to enhance a small office's +operations. Primarily a custom software operation, our vast knowledge of +Windows, DOS, Unix, Windows NT, MacOS, and OS/2 enable us to provide quality +technical assistance to the small office environment at a reasonable price. +Our upcoming multi-mailbox mail client, IQ Mail, enables users with more +than one mailbox to send and retrieve their mail from a single, consistent +mail client running in Windows. + +David J. Fenwick Asset Software, Inc. +President djf@assetsw.com +------------------------------------------------------------------------------ + diff --git a/docs/textdocs/UNIX-SMB.txt b/docs/textdocs/UNIX-SMB.txt new file mode 100644 index 0000000000..b2c064215c --- /dev/null +++ b/docs/textdocs/UNIX-SMB.txt @@ -0,0 +1,220 @@ +This is a short document that describes some of the issues that +confront a SMB implementation on unix, and how Samba copes with +them. They may help people who are looking at unix<->PC +interoperability. + +It was written to help out a person who was writing a paper on unix to +PC connectivity. + +Andrew Tridgell +April 1995 + + +Usernames +========= + +The SMB protocol has only a loose username concept. Early SMB +protocols (such as CORE and COREPLUS) have no username concept at +all. Even in later protocols clients often attempt operations +(particularly printer operations) without first validating a username +on the server. + +Unix security is based around username/password pairs. A unix box +should not allow clients to do any substantive operation without some +sort of validation. + +The problem mostly manifests itself when the unix server is in "share +level" security mode. This is the default mode as the alternative +"user level" security mode usually forces a client to connect to the +server as the same user for each connected share, which is +inconvenient in many sites. + +In "share level" security the client normally gives a username in the +"session setup" protocol, but does not supply an accompanying +password. The client then connects to resources using the "tree +connect" protocol, and supplies a password. The problem is that the +user on the PC types the username and the password in different +contexts, unaware that they need to go together to give access to the +server. The username is normally the one the user typed in when they +"logged onto" the PC (this assumes Windows for Workgroups). The +password is the one they chose when connecting to the disk or printer. + +The user often chooses a totally different username for their login as +for the drive connection. Often they also want to access different +drives as different usernames. The unix server needs some way of +divining the correct username to combine with each password. + +Samba tries to avoid this problem using several methods. These succeed +in the vast majority of cases. The methods include username maps, the +service%user syntax, the saving of session setup usernames for later +validation and the derivation of the username from the service name +(either directly or via the user= option). + +File Ownership +============== + +The commonly used SMB protocols have no way of saying "you can't do +that because you don't own the file". They have, in fact, no concept +of file ownership at all. + +This brings up all sorts of interesting problems. For example, when +you copy a file to a unix drive, and the file is world writeable but +owned by another user the file will transfer correctly but will +receive the wrong date. This is because the utime() call under unix +only succeeds for the owner of the file, or root, even if the file is +world writeable. For security reasons Samba does all file operations +as the validated user, not root, so the utime() fails. This can stuff +up shared development diectories as programs like "make" will not get +file time comparisons right. + +There are several possible solutions to this problem, including +username mapping, and forcing a specific username for particular +shares. + +Passwords +========= + +Many SMB clients uppercase passwords before sending them. I have no +idea why they do this. Interestingly WfWg uppercases the password only +if the server is running a protocol greater than COREPLUS, so +obviously it isn't just the data entry routines that are to blame. + +Unix passwords are case sensitive. So if users use mixed case +passwords they are in trouble. + +Samba can try to cope with this by either using the "password level" +option which causes Samba to try the offered password with up to the +specified number of case changes, or by using the "password server" +option which allows Samba to do it's validation via another machine +(typically a WinNT server). + +Samba also doesn't support the password encryption method used by SMB +clients. This is because the spec isn't sufficiently detailed for an +implementation (although Jeremy Allison is working on it, to try and +work it out). Also, there is a fundamental problem with what we +understand so far in the algorithm, as it seems that the server would +need to store somewhere on disk a reversibly encrypted (effectively +plaintext) copy of the users password in order to use the +algorithm. This goes against the unix policy that "even the super-user +doesn't know your password" which comes from the use of a one-way hash +function. + +Locking +======= + +The locking calls available under a DOS/Windows environment are much +richer than those available in unix. This means a unix server (like +Samba) choosing to use the standard fcntl() based unix locking calls +to implement SMB locking has to improvise a bit. + +One major problem is that dos locks can be in a 32 bit (unsigned) +range. Unix locking calls are 32 bits, but are signed, giving only a 31 +bit range. Unfortunately OLE2 clients use the top bit to select a +locking range used for OLE semaphores. + +To work around this problem Samba compresses the 32 bit range into 31 +bits by appropriate bit shifting. This seems to work but is not +ideal. In a future version a separate SMB lockd may be added to cope +with the problem. + +It also doesn't help that many unix lockd daemons are very buggy and +crash at the slightest provocation. They normally go mostly unused in +a unix environment because few unix programs use byte range +locking. The stress of huge numbers of lock requests from dos/windows +clients can kill the daemon on some systems. + +The second major problem is the "opportunistic locking" requested by +some clients. If a client requests opportunistic locking then it is +asking the server to notify it if anyone else tries to do something on +the same file, at which time the client will say if it is willing to +give up it's lock. Unix has no simple way of implementing +opportunistic locking, and currently Samba has no support for it. + +Deny Modes +========== + +When a SMB client opens a file it asks for a particular "deny mode" to +be placed on the file. These modes (DENY_NONE, DENY_READ, DENY_WRITE, +DENY_ALL, DENY_FCB and DENY_DOS) specify what actions should be +allowed by anyone else who tries to use the file at the same time. If +DENY_READ is placed on the file, for example, then any attempt to open +the file for reading should fail. + +Unix has no equivalent notion. To implement these Samba uses lock +files based on the files inode and placed in a separate lock +directory. These are clumsy and consume processing and file resources, +so they are optional and off by default. + +Trapdoor UIDs +============= + +A SMB session can run with several uids on the one socket. This +happens when a user connects to two shares with different +usernames. To cope with this the unix server needs to switch uids +within the one process. On some unixes (such as SCO) this is not +possible. This means that on those unixes the client is restricted to +a single uid. + +Port numbers +============ + +There is a convention that clients on sockets use high "unprivilaged" +port numbers (>1000) and connect to servers on low "privilaged" port +numbers. This is enforced in Unix as non-root users can't open a +socket for listening on port numbers less than 1000. + +Most PC based SMB clients (such as WfWg and WinNT) don't follow this +convention completely. The main culprit is the netbios nameserving on +udp port 137. Name query requests come from a source port of 137. This +is a problem when you combine it with the common firewalling technique +of not allowing incoming packets on low port numbers. This means that +these clients can't query a netbios nameserver on the other side of a +low port based firewall. + +The problem is more severe with netbios node status queries. I've +found that WfWg, Win95 and WinNT3.5 all respond to netbios node status +queries on port 137 no matter what the source port was in the +request. This works between machines that are both using port 137, but +it means it's not possible for a unix user to do a node status request +to any of these OSes unless they are running as root. The answer comes +back, but it goes to port 137 which the unix user can't listen +on. Interestingly WinNT3.1 got this right - it sends node status +responses back to the source port in the request. + + +Protocol Complexity +=================== + +There are many "protocol levels" in the SMB protocol. It seems that +each time new functionality was added to a Microsoft operating system, +they added the equivalent functions in a new protocol level of the SMB +protocol to "externalise" the new capabilities. + +This means the protocol is very "rich", offering many ways of doing +each file operation. This means SMB servers need to be complex and +large. It also means it is very difficult to make them bug free. It is +not just Samba that suffers from this problem, other servers such as +WinNT don't support every variation of every call and it has almost +certainly been a headache for MS developers to support the myriad of +SMB calls that are available. + +There are about 65 "top level" operations in the SMB protocol (things +like SMBread and SMBwrite). Some of these include hundreds of +sub-functions (SMBtrans has at least 120 sub-functions, like +DosPrintQAdd and NetSessionEnum). All of them take several options +that can change the way they work. Many take dozens of possible +"information levels" that change the structures that need to be +returned. Samba supports all but 2 of the "top level" functions. It +supports only 8 (so far) of the SMBtrans sub-functions. Even NT +doesn't support them all. + +Samba currently supports up to the "NT LM 0.12" protocol, which is the +one preferred by Win95 and WinNT3.5. Luckily this protocol level has a +"capabilities" field which specifies which super-duper new-fangled +options the server suports. This helps to make the implementation of +this protocol level much easier. + +There is also a problem with the SMB specications. SMB is a X/Open +spec, but the X/Open book is far from ideal, and fails to cover many +important issues, leaving much to the imagination. + diff --git a/docs/textdocs/WinNT.txt b/docs/textdocs/WinNT.txt new file mode 100644 index 0000000000..b57abb7742 --- /dev/null +++ b/docs/textdocs/WinNT.txt @@ -0,0 +1,56 @@ +There are some particular issues with Samba and Windows NT + +===================================================================== +One of the most annoying problems with WinNT is that NT refuses to +connect to a server that is in user level security mode and that +doesn't support password encryption unless it first prompts the user +for a password. + +This means even if you have the same password on the NT box and the +Samba server you will get prompted for a password. Entering the +correct password will get you connected. + +The other major ramification of this feature of NT is that it can't +browse a user level non-encrypted server unless it already has a +connection open. This is because there is no spot for a password +prompt in the browser window. It works fine if you already have a +drive mounted (for example, one auto mounted on startup). + +Samba should support encrypted passwords soon, which will solve this +problem. +===================================================================== + + + +===================================================================== +When you mount a printer using the print manager in NT you may find +the following info from Matthew Harrell +useful: + +------------ + I noticed in your change-log you noted that some people were +still unable to use print manager under NT. If this is the same problem +that I encountered, it's caused by the length of time it takes NT to +determine if the printer is ready. + +The problem occurs when you double-click on a printer to connect it to +the NT machine. Because it's unable to determine if the printer is ready +in the short span of time it has, it assumes it isn't and gives some +strange error about not having enough resources (I forget what the error +is). A solution to this that seems to work fine for us is to click +once on the printer, look at the bottom of the window and wait until +it says it's ready, then clilck on "OK". + +By the way, this problem probably occurs in our group because the +Samba server doesn't actually have the printers - it queues them to +remote printers either on other machines or using their own network +cards. Because of this "middle layer", it takes an extra amount of +time for the NT machine to get verification that the printer queue +actually exists. + +I hope this helped in some way... +----------- +===================================================================== + + + -- cgit